# SSO Login

{% hint style="info" %}
**Testing:** Need test users for development? See [How to Get Test Users](/dupr-raas/reference/developer-faq.md#how-to-get-test-users) in the Developer FAQ.
{% endhint %}

{% hint style="warning" %}
**API Access Restrictions:** Partners are subject to access restrictions that limit API interactions to users who have completed the SSO flow. When restricted:

* **User Details & Match History** — Requests for users who have not authenticated via SSO will return a `403 Forbidden` error.
* **User Search** — Results are automatically filtered to only include connected users.
* **Match Submission** — Partners can submit matches for users who have not completed SSO, but will not be able to retrieve those match results until the user has connected their account.
* **Rating Subscriptions** — Subscribing to ratings for unconnected users will return a `400 Bad Request` error listing the unconnected DUPR IDs.
* **Match Data** — Players who have not authenticated via SSO will be masked (displayed as "A DUPR User" with personal details removed).

Partners must ensure the SSO flow is completed for each user before attempting to access their data or submit matches on their behalf.
{% endhint %}

## Implementation

To integrate the login, embed the following URL into an `<iframe>` on your site.

<table data-header-hidden><thead><tr><th width="158">Environment</th><th>iframe Embed Code</th></tr></thead><tbody><tr><td>UAT</td><td><code>&#x3C;iframe src="https://uat.dupr.gg/login-external-app/:clientKey" allow="payment">&#x3C;/iframe></code></td></tr><tr><td>Production</td><td><code>&#x3C;iframe src="https://dashboard.dupr.com/login-external-app/:clientKey" allow="payment">&#x3C;/iframe></code></td></tr></tbody></table>

{% hint style="info" icon="circle-exclamation" %}
`:clientKey` must be the **Base64 encoded** version of the `clientKey` provided during your onboarding. This is **not** the same as your Access Token; do not include your `clientSecret` here.
{% endhint %}

<figure><img src="/files/lpRqJzeNIROM6IUjObhF" alt=""><figcaption></figcaption></figure>

***

## User Consent

After logging in, users are presented with a consent screen where they can explicitly authorize which data your platform can access. Required fields (DUPR ID, Partial Name, Ratings, Birth Year) cannot be opted out of, while optional fields (Full Name, Gender, Location) can be toggled on or off by the user.

<figure><img src="/files/nsLluILf0GlDpWj6ousH" alt=""><figcaption></figcaption></figure>

The data a user consents to share is reflected in the response from the [Get Basic User Info](#identity-verification) endpoints.

{% hint style="warning" %}
Users can modify or revoke their consent at any time through their DUPR profile settings. This includes revoking individual data permissions or disconnecting from your platform entirely. Your integration should handle cases where previously available data may no longer be accessible.
{% endhint %}

***

## Handling the Login Response

Once a user successfully logs in, the embedded DUPR JS emits an event to the parent window. You must set up a listener to capture the user’s tokens and profile data.

```javascript
// This is provided only as an example, and must be adapted to your implementation!
function handleMessage(event){
	$("#userToken").val(event.userToken);
	$("#refreshToken").val(event.refreshToken);
	$("#userId").val(event.id);
	$("#duprId").val(event.duprId);
	$("#stats").val(event.stats); 
}
window.addEventListener('message', handleMessage, false);
```

\
This event can also be used to close the iframe (or mobile webview) in response to the user successfully logging in. Once you have the access token for the user, you can make additional API calls in order to get more information. It is important to mention that this user access token has read only permissions and cannot be used to modify data on the user's behalf.

***

## Using User Access Tokens

The `accessToken` and `refreshToken` retrieved from the SSO flow can be stored on your server to interact with DUPR on the user's behalf.

#### Token Expiration

<table><thead><tr><th width="158">Environment</th><th width="200">Access Token</th><th>Refresh Token</th></tr></thead><tbody><tr><td>UAT</td><td>7 days</td><td>30 days</td></tr><tr><td>Production</td><td>30 days</td><td>90 days</td></tr></tbody></table>

#### Refreshing Tokens

When the `accessToken` expires, use the `refreshToken` to obtain a new token pair without requiring the user to log in again.

<table><thead><tr><th width="158">Environment</th><th>API</th></tr></thead><tbody><tr><td>UAT</td><td><a href="https://api.uat.dupr.gg/api-explorer?group=public#/Auth/refreshAccessToken">UAT: Refresh Access Token</a></td></tr><tr><td>Production</td><td><a href="https://api.dupr.gg/api-explorer?group=public#/Auth/refreshAccessToken">Prod: Refresh Access Token</a></td></tr></tbody></table>

The response contains a new `accessToken` and `refreshToken`. Store both — the refresh token is also rotated on each use.

{% hint style="warning" %}
If the `refreshToken` has also expired, the user must complete the SSO login flow again.
{% endhint %}

#### Key Capabilities & Constraints

* Scoped Access: These tokens grant access to specific non-Partner APIs (e.g., retrieving user profiles or verifying ratings).
* Read-Only Permission: It is important to note that these tokens carry read-only permissions. They cannot be used to modify user data or perform administrative actions.
* Documentation: Available endpoints are documented throughout these docs. New supported APIs are added regularly.

{% hint style="danger" %}
Usage of these user access tokens outside of the specific non-Partner APIs mentioned in these docs are strictly prohibited.
{% endhint %}

#### Identity Verification

To confirm a user's identity and retrieve their DUPR ID, use the following profile endpoints:

<table><thead><tr><th width="158">Environment</th><th>API</th></tr></thead><tbody><tr><td>UAT</td><td><a href="https://api.uat.dupr.gg/api-explorer?group=public#/Public/getBasicInfo">UAT: Get Basic User Info</a></td></tr><tr><td>Production</td><td><a href="https://api.dupr.gg/api-explorer?group=public#/Public/getBasicInfo">Prod: Get Basic User Info</a></td></tr></tbody></table>

{% hint style="warning" %}
Always include the User Access Token in the authorization header for these calls. Using a Partner Token for these specific endpoints will result in an authorization error.
{% endhint %}

***

## Troubleshooting

If you encounter errors during the login flow, check the common causes below:

<table><thead><tr><th width="255">Error Message</th><th width="165">Potential Cause</th><th width="314">Potential Fix</th></tr></thead><tbody><tr><td>This DUPR partner has an invalid or incomplete integration. Please reach out to their support team to report this issue [Missing or invalid clientKey]</td><td>Incorrect clientKey in the url of the &#x3C;iframe/></td><td>Ensure the client key is correctly base 64 encoded in the iframe url: <a href="#implementation">Implementation</a></td></tr><tr><td>The user's credentials are not valid, or the user is disabled. Please check your username and password, and try again.</td><td>The user does not exist in the environment (e.g., trying to use Prod creds in UAT).</td><td><strong>UAT:</strong> <a data-mention href="/pages/DLWUxyrd2nrEcCdXjcCT#how-to-get-test-users">/pages/DLWUxyrd2nrEcCdXjcCT#how-to-get-test-users</a><br><br><strong>Prod:</strong> Create the user at <a href="https://dashboard.dupr.com/signup">https://dashboard.dupr.com/signup</a> or reset the user's password at <a href="https://dashboard.dupr.com/password">https://dashboard.dupr.com/password</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dupr.gitbook.io/dupr-raas/integration-checklist/sso-login.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.