Skip to main content

Client authentication

Loading...

Client APIs are endpoints that allow you to access Unity Services as a Unity project user. These endpoints are called inside the project after a user has performed an action.

To authenticate with client APIs, you must use the Unity Authentication service. This service provides anonymous and platform-specific authentication solutions for client APIs.

Unity Authentication is currently supported for the following Unity Gaming Services:

Overview

Unity Authentication supports authenticating players via anonymous authentication and with Platform-Specific authentication.

How it works​

When a returning or new player logs into your app, Unity Authentication generates the following tokens and Id:

  • PlayerId: The PlayerId is the main identifier for Unity Authentication end players, identifying returning and new players. It’s unique per Unity Project. It’s a random string of numbers, lowercase letters, and uppercase letters.
  • Session token: A token that’s used to re-authenticate the player after the session expires. It's a randomly generated string. In the authentication responses, the field is called sessionToken.
  • Authentication Id Token: A JWT that contains a set of claims, including the PlayerId. It’s passed into APIs for other Unity services to provide authorization. Other Unity Service’s APIs need this token to authorize actions. In the API responses, the field is called idToken.

Login States​

You're responsible for respecting when a player is logged in vs logged out.

  • A player is considered logged in when you have a valid id token for that player.
  • A player is considered logged out when you have an invalid id token for that player.

You're responsible for verifying that the id token is valid. For more information on how to verify the id token, refer to the Validating the idToken section. If the id token is expired and you want to keep the player logged in, then you must refresh the id token. Refer to the Refreshing the idToken section.

Use Cases​

These tokens and the PlayerId allow Unity products and Unity games to capture player information during authentication. They enable:

  • A means to identify a player and store player game data (for example, saving game state and recording in-app purchases).
  • Consistent game experiences for the player (for example, points for leader boards and suggested in-app purchases).
  • Insight about the player’s game behavior across multiple devices.
  • Multiplayer features on various platforms.
  • Digital Services Act notifications

Types of authentication​

Anonymous authentication​

Anonymous authentication is similar to a guest sign-in. It creates a new player for the game session without any input from the player. The player won't need to enter any sign-in credentials or to create a player profile. It's a quick way for a player to get started with your game.

Although this method has the lowest friction for players, anonymous authentication is not portable across devices since there is no way to re-authenticate the player from another device. Players aren’t able to sign in to the same game with the same player profile from a different device unless they use platform-specific authentication.

Username Password Authentication​

Username Password authentication allows players to create a username and password to sign in to your game. This method is portable across devices, so players can sign in to the same game with the same player account from a different device. This method also allows players to sign in to your game without using a third-party identity provider.

Code Linking​

Code Linking enables a player to securely sign in to your game from one device to another using a temporary generated code. This method is portable across devices, so players can sign in to the same game with the same player account from a different device.

Custom ID​

Custom ID allows developers to use their existing authentication systems to authentication their players with Unity Authentication. Developers can provision a service account and use that service account to exchange their own players ids for a Unity Authentication player id.

Platform-specific Authentication​

Platform-specific authentication uses external identity providers. This means that you must create an identity provider configuration so that Unity Authentication can validate the player, making it possible to authenticate the same player from multiple devices.

The following Unity Gaming Services support Unity Authentication:

Set up the Unity Authentication service​

When a new or returning user logs into your application, the Unity Authentication service uses the following to capture the user's information:

  • PlayerId: the main identifier for new and returning Unity Authentication end users.
  • sessionToken: a randomly-generated string that re-authenticates the user after the session expires.
  • idToken: a JSON Web Token (JWT) that contains a set of claims, including the PlayerId. The idToken provides authorization when passed into other Unity Services APIs.

The PlayerId, sessionToken, and idToken provide:

  • A way to identify a user and to store user data. For example, saving the game state and recording in-app purchases.
  • Consistent game experiences for the user. For example, points for leaderboards and suggested in-app purchases.
  • Insight about the user's game behavior across multiple devices.
  • Multiplayer features on different platforms.

The Unity Authentication service supports user authentication through anonymous or platform-specific authentication.

Set up anonymous authentication​

Anonymous authentication is similar to a guest login. It allows the user to create a new user for the game session without entering login credentials or creating a profile.

To set up anonymous authentication, follow these steps:

  1. Find your Unity project ID in the Project Details section of your project in the Unity Dashboard.
  2. Call the following API to create an anonymous player ID:
curl -XPOST -H "ProjectId: <projectId>" https://player-auth.services.api.unity.com/v1/authentication/anonymous \
-H 'Content-Type: application/json'
  1. Find the idToken and sessionToken fields in the JSON response object. The response will look similar to this:
{
    "userId": "T7galGM3T1Bggbb3FfNrzMdivZOG",
    "idToken": "eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ",
    "sessionToken": "R5pKaP8kEUE2aG...pk08RGC7aM",
    "expiresIn": 3599,
    "user": {
        "id": "T7galGM3T1Bggbb3FfNrzMdivZOG",
        "disabled": false,
        "externalIds": []
    }
}

You can use the idToken as the user's authentication token when you call client APIs. To do so, include the idToken in the authorization header as the bearer token:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ" \
https://services.api.unity.com/<ENDPOINT>

Set up Username Password authentication​

Username Password Authentication allows players to create a username and password to sign in to your game. This method is portable across devices, so players can sign in to the same game with the same player profile from a different device. This method also allows players to sign in to your game without using a third-party identity provider.

Setup Steps​

  1. Log into the Unity Dashboard.
  2. Select your project.
  3. On the left side of the page, select the LiveOps button.
  4. Under the LiveOps tab, select the Authentication drop-down and select Identity Providers.
  5. On the right side, select Add Identity Provider, and select Username Password.
  6. Select Add Identity Provider.

Sign Up​

To sign a player up, call the API below:


curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/usernamepassword/sign-up' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>' \
--data-raw '{
    "username": "<username of the user>",
    "password": "<password of the user>"
}'

Note that Authorization is an optional header. If the Authorization Header is not provided, then a new player is created. Otherwise, the API adds the username password to the existing player indicated by the ID token. The ID token can be retrieved from other authentication APIs, such as Anonymous sign-up, session token sign-in, external token auth, etc.

Username and Password restrictions​

Below are the restrictions for both the username and password fields:

Username​

  • The username must be between 3-20 characters long.
  • The username can only contain the following characters: a-z, 0-9, and the symbols [.][-][@][_].
  • The username is case-insensitive.

Password​

  • The password must be between 8-30 characters long.
  • The password must contain at least one uppercase letter.
  • The password must contain at least one lowercase letter.
  • The password must contain at least one number.
  • The password must contain at least one symbol.

Sign In​

To sign a player in, call the API below:

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/usernamepassword/sign-in' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
    "username": "<username of the user>",
    "password": "<password of the user>"
}'

Password update​

To update the password of a user, call the API below:

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/usernamepassword/update-password' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>' \
--data-raw '{
    "password": "<password of the user>",
    "newPassword": "<the password to be changed>"
}'

Note that Authentication is a required header and must be specified in the request. This is because the user must be signed in to update their password. For the new password, the same restrictions apply as when signing up a user.

Code Linking​

Code Linking is a cross-platform authentication method that allows players to sign in across multiple devices by using a securely generated temporary code. This uses the Proof Key for Code Exchange (PKCE) protocol to ensure that only the client that generated the code can be authenticated from the code flow.

How Code Linking Works​

  1. The game client requests a code from the unauthenticated device to which the user wants to sign in. A codeChallenge is provided in this Generate Sign In Code request.
  2. Once the request is made, a signInCode is sent back as a response.
  3. The player will then need to confirm the signInCode by entering it into the game client on the authenticated device.
  4. Next, the game client then calls the Code Confirmation API from an already authenticated device and include the signInCode within the request. This confirms that the unauthenticated device can be properly linked to the player's account.
  5. Lastly, the game client can now call the Sign in With Code API from the unauthenticated device, and include the codeVerifier within the request. The codeVerifier will be checked against the hashed codeChallenge, and if they match, the device will be signed in and authenticated.

Generating a codeChallenge and codeVerifier​

The codeChallenge is a SHA-256 hashed value generated from a codeVerifier. The codeVerifier is a randomly generated base64 encoded string that is used to generate a codeChallenge. Both of these values must be between the lengths of 43-128 characters.

To generate a codeVerifier, use the following code:

package main
import (
    "crypto/rand"
    "encoding/base64"
    "fmt"
)
func main() {
    b := make([]byte, 64)
    _, err := rand.Read(b)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    s := base64.StdEncoding.EncodeToString(b)
    fmt.Println(s)
}

To generate a codeChallenge, use the following code:

package main
import (
    "crypto/sha256"
    "encoding/base64"
    "fmt"
)
func main() {
    s := "codeVerifier" // Replace this with your base64 codeVerifier string
    b := sha256.Sum256([]byte(s))
    encoded := base64.StdEncoding.EncodeToString(b[:])
    fmt.Println(encoded)
}

For more information on how these values are formatted, please check out: PKCE.

Setup Steps​

  1. Log into the Unity Dashboard.
  2. Select your project.
  3. On the left side of the page, select the LiveOps button.
  4. Under the LiveOps tab, select the Authentication drop-down and select Identity Providers.
  5. On the right side, select Add Identity Provider, and select Code Linking.
  6. Click Add Identity Provider.

Generate Sign In Code​

This API requests a code to be generated for an unauthenticated device. The player will need to confirm the sign in request on an already authenticated device in order to sign in to the new device. To generate a sign-in code, call the API below:

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/code-link/generate' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
    "codeChallenge": "<string>",
    "identifier": "<string>"
}'

Field information:

  • codeChallenge: The code challenge that will be used to validate the code verifier sent in subsequent Sign In with Code requests, ensuring that those requests originated from the same device that generated the sign-in code.
  • identifier: An optional identifier that can be used to identify the device or to provide a hint for the unauthenticated device.

The response will contain several values:

  • codeLinkSessionId: A unique identifier for the code-linking session.
  • signInCode: The code used as input in an authorized device.
  • expiration: The timestamp of when the signInCode will expire.

Sign In with Code​

This API signs a player in using a codeLinkSessionId and a codeVerifier to identify the original request. A codeLinkSessionId is passed as a parameter, and is used to specify the code-linking session associated with the initial unauthenticated device.

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/code-link/sign-in/<codeLinkSessionId>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
    "codeVerifier": "<string>"
}'

Field information:

  • codeVerifier: Validates the original request came from the same device.
  • sessionToken: The session token of the authenticated user.

Get Code Information (Optional)​

This optional API can be used by an authenticated client to get information about the sign in code or to verify you are attempting to code link to the correct unauthenticated device. To call this API, no authentication is required.

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/code-link/info' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
    "signInCode": "<string>"
}'

Field information:

  • signInCode: The code that is required to get information from an authorized device.

The response will contain an identifier, which can be used to identify the device that requested the code.

{
  "identifier": "<string>", // Identifies the device for extra confirmation (Optional)
}

Code Confirmation​

This API is used by an authenticated client to confirm code linking for an unauthenticated device. This verifies that the device that requested the code is the same device that is attempting to sign in.

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/code-link/confirm' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>' \
--data-raw '{
    "signInCode": "<string>",
    "sessionToken": "<string>"
}'

Field information:

  • signInCode: The code that is required to get information from an authorized device.
  • sessionToken: The session token of the authenticated user.

Digital Services Act Notifications​

To comply with the Digital Services Act, which takes full effect on February 17, 2024, you must integrate with the new Notifications APIs. Refer to our DSA compliance efforts page for more information.

This article explains how to integrate with the Notification APIs to:

  • Check for new notifications for a signed in player.
  • Check for new notifications for a restricted player.

Notifications for signed in player​

Every time a player successfully signs in, the Authentication SDK validates if there are any notifications available for that player and populates the lastNotificationDate field in the AuthenticationResponse, with the date the last notification was created, in milliseconds, since Unix epoch. You must:

  1. Confirm the lastNotificationDate field is not null after every successful sign in, meaning there are notifications available for that player.
  2. Confirm if the lastNotificationDate is greater than the value you stored for the last notification the player read.
  3. Retrieve the player's notifications by calling the ReadNotifications API.
curl --location 'https://player-auth.services.api.unity.com/v1/users/<playerId>/notifications' \
--header 'projectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>'
{
    "notifications": [
        {
            "id": <string>, // Notification ID
            "type": <string>, // DSA
            "playerID": <string>,
            "caseID": <string>, 
            "projectID": <string>, 
            "message": <string>, // Message details that should be displayed to the player,
            "createdAt": <int> // Unix epoch timestamp
        }, ...
    ]
}
  1. Display the notifications to the player.
  2. When the player reads a notification you must store the greater value between that notification's createdAt value and the stored value for the player's last read notification.

Notifications for a restricted player​

When a player tries to sign in and fails due to them being restricted, an AuthenticationError response is returned and it contains a new notifications field in the details, which contains all notifications available to that player, or null if none are available. You must:

  1. Parse the AuthenticationError response, after every failed sign in attempt.
{
    "status":403,
    "title":"BANNED_USER",
    "detail":"The user is banned until 2025-01-01 00:00:00 +0000 UTC",
    "details":[
        {
            "notifications": [
                {
                    "id": <string>, // Notification ID
                    "type": <string>, // DSA
                    "playerID": <string>,
                    "caseID": <string>, 
                    "projectID": <string>, 
                    "message": <string>, // Message details that should be displayed to the player,
                    "createdAt": <int> // Unix epoch timestamp
                }, ...
            ]
        }
    ]
}
  1. Confirm if the notifications field in the details isn't null.
  2. Display the notifications to the player.

Custom ID authentication​

Custom ID authentication allows the player to authenticate with your existing authentication game server and use the game server's player id with a service account to exchange for a Unity player id.

The following steps will guide you to set up your game with the ability for players to sign in to your game using your existing authentication system and get an access token.

Setup​

  1. Log into the Unity Dashboard.
  2. Select your project.
  3. On the left side of the page, select LiveOps.
  4. Under the LiveOps tab, select the Authentication drop-down and select Identity Providers.
  5. On the right side, select Add Identity Provider, and select Custom ID.
  6. Select Add Identity Provider.

Set up Service Account​

To use the Custom ID authentication you need to Create a Service Account to authenticate your game server with Unity Authentication. You also need to add the project role Player Authentication Token Issuer to the Service Account, to authorize the game server to perform the Custom ID authentication.

Find your Unity Project Id​

  1. Open the Unity Dashboard.
  2. Access the Projects page from the left menu.
  3. Open the project that you want to use to call Client APIs.
  4. Find the Project Id in the Project Details.

Authenticate with Custom ID​

To perform the Custom ID authentication follow these steps:

  1. Authenticate the player on your game server.

  2. Call the Token Exchange API to retrieve a stateless token if not expired

curl -X POST -H "Authorization: Basic <SERVICE_ACCOUNT_KEY_ID>:<SECRET_KEY>" \
https://services.api.unity.com/auth/v1/token-exchange?projectId=<PROJECT_ID>&environmentId=<ENVIRONMENT_ID>

  1. Exchange the game server's player id for a Unity player id
curl -X POST -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <STATELESS_TOKEN>' \
-d '{
    "externalId": <GAME_SERVER_PLAYER_ID>,
    "signInOnly": false
}' \
https://player-auth.services.api.unity.com/v1/projects/<PROJECT_ID>/authentication/server/custom-id
'

The API will respond with a JSON object. Find the idToken and sessionToken fields in the JSON object. The response will look like:

{
    "userId": "T7galGM3T1Bggbb3FfNrzMdivZOG",
    "idToken": "eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ",
    "sessionToken": "R5pKaP8kEUE2aG...pk08RGC7aM",
    "expiresIn": 3599,
    "user": {
        "id": "T7galGM3T1Bggbb3FfNrzMdivZOG",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "custom",
                "externalId": <GAME_SERVER_ID>
            }
        ]
    }
}

The idToken can then be used to call Client APIs as the player's Authentication token when needed. The token should be placed in the Authorization header as a Bearer token. For example:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs...p_q74teH0MNTMQ" \
https://services.api.unity.com/<ENDPOINT>

To link an existing Unity Authentication account with a Custom ID from your own authentication service you can follow these steps:

  1. Authenticate the player with UAS using any other sign-in method.

  2. When authenticating the player with your Authentication system, send the idToken from the authentication response.

  3. Follow the steps in Authenticate with Custom ID, but in step three include the idToken in the payload as the accessToken field:

curl -X POST -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <STATELESS_TOKEN>' \
-d '{
    "externalId": <GAME_SERVER_PLAYER_ID>,
    "signInOnly": false,
    "accessToken": <idToken>
}' \
https://player-auth.services.api.unity.com/v1/projects/<PROJECT_ID>/authentication/server/custom-id
'

Platform-Specific Authentication​

Set up platform-specific authentication​

Platform-specific authentication uses external identity providers to authenticate users. It provides the user with a consistent login method and allows them to access their account from different devices.

You can set up the following identity providers for platform-specific authentication:

You can set up an identity provider through:

  • The Editor settings in the Unity Editor, if you have the Unity Authentication SDK. For more information on setting up an identity provider with the Unity Editor, refer to Set up external identity providers.
  • The Unity Dashboard.

Apple​

To set up the Apple identity provider, follow these steps:

  1. Register and configure an application with Apple and find your Apple Client ID.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > Sign in with Apple.
  5. Enter your App ID and enable the Enable Identity Provider checkbox.
  6. Select Add provider.

Apple Game Center​

To set up the Apple Game Center identity provider, follow these steps:

  1. Register and configure an application with the Apple Game Center and find your Bundle ID.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > Apple Game Center.
  5. Enter your Bundle ID and enable the Enable Identity Provider checkbox.
  6. Select Add provider.

Facebook​

To set up the Facebook identity provider, follow these steps:

  1. Register and configure an application as a Meta developer and find your App ID and App Secret.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > Facebook.
  5. Enter your Ap ID and Secret ID, and enable the Enable Identity Provider checkbox.
  6. Select Add provider.

Google​

To set up the Google identity provider, follow these steps:

  1. Register and configure an application with Google and find your Client ID.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > Sign in with Google.
  5. Enter your Client ID and enable the Enable Identity Provider checkbox.
  6. Select Add provider.

Google Play Games​

To set up the Google Play Games identity provider, follow these steps:

  1. Register and configure an application with Google Play Games and find your Client ID and Client Secret.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > Google Play Games.
  5. Enter your Client ID and Client Secret, and enable the Enable Identity Provider checkbox.
  6. Select Add provider.

Oculus​

o set up the Oculus identity provider, follow these steps:

  1. Register and configure an application with Oculus and find your App ID and App Secret.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > Oculus.
  5. Enter your App ID and Secret ID, and enable the Enable Identity Provider checkbox.
  6. Select Add provider.

Custom OpenID Connect (OIDC)​

To set up the OIDC identity provider, follow these steps:

  1. Register and configure an application with the OIDC provider and find your Client ID and Issuer URL.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > OpenID Connect.
  5. Enter a name for your OIDC provider, your Client ID, and your Issuer URL.
  • The name for your OIDC provider:
  • Must start with oidc-.
  • Must have a maximum length of 20 characters, including the oidc- prefix.
  • Can contain a-z lowercase characters, 0-9 number characters, or the ., -, _ characters.
  • Your Issuer URL:
  • Must be in the https protocol scheme.
  • Must have a maximum length of 100 characters.
  • Can't have an openid-configuration response larger than 20000 bytes.
  • Can't have a jwks response larger than 20000 bytes.
  1. Enable the Enable Identity Provider checkbox.
  2. Select Add provider.

Steam​

To set up the Steam identity provider, follow these steps:

  1. Register and configure an application with Steam and find your App ID and Key.
  2. Go to the Unity Dashboard and select the project you want to authenticate.
  3. Under Suites, go to LiveOps > Authentication > Identity Providers.
  4. Select Add Identity Provider > Steam.
  5. Enter your App ID and Key, and enable the Enable Identity Provider checkbox.
  6. Select Add provider.

To set up Multiple App Ids (e.g.: Play Test, Demo, Alpha, etc), follow these steps:

  1. Go to the Unity Dashboard and select the project you want to authenticate.
  2. Under Suites, go to LiveOps > Authentication > Identity Providers.
  3. Click the Steam provider already set up for your project to Edit.
  4. Click the Add button to the right of Additional App ID.
  5. Input the App ID and a Description.
  6. Click Save.

Platform-specific authentication APIs​

When a user logs into the identity provider, you gain access to their access token. You can pass their access token into one of the following APIs:

  • External token API
  • Link API
  • Unlink API

These APIs require a project ID and an ID provider as inputs. To find your project ID, go to the Project Details section of your project in the Unity Dashboard. The project ID is sent as a header and the identity provider is sent as part of the API path.

Use the following constant values as inputs when you call platform-specific authentication APIs:

  • For Apple: apple.com
  • For Apple Game Center: apple-game-center
  • For Facebook: facebook.com
  • For Google: google.com
  • For Google Play Games: google-play-games
  • For Oculus: oculus
  • For OIDC: the name you configured for your OIDC provider
  • For Steam: steampowered.com

Example​

  "token": "<Access or Id token from Third Party>"

External token API​

The external token API creates or logs in a Unity Authentication account with a platform-specific identity. Use the external token API when:

  • The user isn't logged into Unity Authentication
  • The user is logged into the identity provider
  • You want the user to log in with their identity provider access token

After you call the external token API, the Unity Authentication service creates a new user and links them to the external identity you specified on the access token.

You don't need to call the external token API again after you have successfully called it once.

Example​

  "token": "<Access or Id token from Third Party>"

JSON object response example:

{
    "userId": "Z1bNra4q4LSnyl3P9HM2ohb6Ub3f",
    "idToken": "eyJhbG...Tj0ew",
    "sessionToken": "YgYyi...KbrU",
    "expiresIn": 3599,
    "user": {
        "id": "Z1bNra4q4LSnyl3P9HM2ohb6Ub3f",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "<Id Provider>",
                "externalId": "<Player's External Id>"
            }
        ]
    }
}

Oculus API input​

To log in with the Oculus identity provider, you must include the user ID and the nonce as inputs in the API request body.

{
    "token": "<Nonce from Oculus>",
    "oculusConfig": {
        "userId": "<player Id from Oculus>"
    }
}

For more information, refer to the Oculus documentation.

Steam API optional input​

The Steam Identity provider has an optional configuration object, steamConfig for:

  • Increased security by including the identity field, which MUST be the same as then one used when requesting the steam ticket.
  • Multiple App Id support by including the appId used to request the steam ticket. Note: This needs to have been previously configured in the dashboard
{
    "token": "<Ticket token>",
    "steamConfig": {
        "identity": "<string>",
        "appId": "<string>"
    }
}

Apple Game Center API input​

To log in with the Apple Game Center identity provider, you must include the following values:

  • Signature, which is contained inside the token field
  • Team player ID
  • Salt
  • Timestamp
  • Public key URL

The signature and salt values in your API request body must be Base64 encoded string values of the raw value you got from Apple. The timestamp input is only valid for 10 minutes.

{
    "token": "<Signature from Apple Game Center>",
    "appleGameCenterConfig": {
        "teamPlayerId": "<Team Player Id from Apple Game Center>",
        "salt": "<Salt from Apple Game Center>",
        "timestamp": "<Timestamp from Apple Game Center>",
        "publicKeyUrl": "<Public Key Url from Apple Game Center>"
    }
}

Prevent the creation of a new user​

By default, the external token API creates a new user on the Unity Authentication service if a user doesn't already exist. To prevent the creation of a new Unity Authentication user, set the signInOnly flag to true.

If the user doesn't exist, the API request fails and doesn't create a new user.

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/external-token/<Id Provider>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--data-raw '{
    "token": "<Access or Id token from Third Party>",
    "signInOnly": true
}'

The link API links a Unity Authentication account with a platform-specific identity. Use the link API when:

  • The user is logged into Unity Authentication
  • The user is logged into the identity provider
  • You want to link the Unity Authentication user to the external identity

The user's Unity Authentication ID token is used to authorize actions on their account. Make sure to save the user's ID token from a previous authentication response.

After you call the link API, the user becomes linked to the external identity.

Example​

Link API call example:

    "token": "<Access or Id token from Third Party>"

JSON object response example:

{
    "userId": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
    "idToken": "",
    "sessionToken": "",
    "expiresIn": 0,
    "user": {
        "id": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
        "disabled": false,
        "externalIds": [
            {
                "providerId": "<Id Provider>",
                "externalId": "<External Id>"
            }
        ]
    }
}

You can only link a single Unity Authentication user to an external identity. Your link API request fails if another user is already linked to the identity.

To disconnect the external identity from the already-linked user and link it to a different user instead, set the forceLink flag to true.

    "token": "<Access or Id token from Third Party>",
    "forceLink": true

The unlink API unlinks a Unity Authentication account from a platform-specific identity. Use the unlink API when:

  • The user is logged into Unity Authentication
  • You want to unlink the Unity Authentication user from the external identity

To unlink a user, you must have their external ID. You can find the external ID in the externalIds field of the external token or link API responses.

The user's Unity Authentication ID token is used to authorize actions on their account. Make sure to save the user's ID token from a previous authentication response.

After you call the unlink API, the user becomes unlinked from the external identity.

Example​

Unlink API call example:

    "externalId": "<Third Party External Id>"

JSON object response example:

{
    "userId": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
    "idToken": "",
    "sessionToken": "",
    "expiresIn": 0,
    "user": {
        "id": "WIIXBaxb5g1Y5ZPwbZErapmbOcTl",
        "disabled": false,
        "externalIds": []
    }
}

Get player API​

The get player API checks information about the user. Use the get player API when:

  • The user is logged into Unity Authentication
  • You need information about the user

Example​

Get player API call example:

curl --location --request GET 'https://player-auth.services.api.unity.com/v1/users/<playerId>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>'

JSON object response example:

{
    "id": "Tg1m3aq3nVEb9o9kG4vNeqcixLH8",
    "disabled": false,
    "externalIds": [],
    "createdAt": "302899439",
    "lastLoginAt": "302899439",
    "username": "Current_User_57"
}

Delete player API​

The delete player API deletes the user. Use the delete player API when:

  • The user is logged into Unity Authentication
  • You need to delete the user

Example​

Delete player API call example:

curl --location --request DELETE 'https://player-auth.services.api.unity.com/v1/users/<playerId>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>'

JSON object response example:

{}

The response is an empty object because the user information has been deleted.

Non-platform-specific authentication APIs​

Validate the token ID​

To check the login status of a user, you must verify the status of their token ID. Logged in users have a valid token ID, while logged out users have an invalid token ID.

The idToken is a JWT that can be verified. For more information about JWTs, refer to the RFC 7519 JWT overview.

To validate the idToken, follow these steps:

  1. Fetch the JSON Web Key Set (JWKS) from Unity Authentication. The JWKS has the public key used to validate tokens.
  2. Verify the signature of the tokenId to make sure that the token is signed by the Unity Authentication server and that the token's claims haven't been modified.
  3. Decode the base64url-encoded tokenId.
  4. Verify that the claims are valid.

Fetch the JWKS​

To fetch the JWKS, access the following endpoint:

https://player-auth.services.api.unity.com/.well-known/jwks.json

The response is a standard JWKS.

{
    "keys": [
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "public:f66a7494-5315-4ca4-8150-e846573ffc1d",
            "alg": "RS256",
            "n": "...",
            "e": "AQAB"
        },
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "public:c2f38f4a-a115-40a4-a530-10d08211b6ac",
            "alg": "RS256",
            "n": "...",
            "e": "AQAB"
        }
    ]
}

For better results, refresh your JWKS every 8 hours. If you can't find the idToken in the cached JWKS, fetch the JWKS again. Make sure not to refresh the JWKS too frequently or a rate limit will be enforced. For more information on the rate limit, refer to the Rate limits page.

Verify claims​

To make sure that your token is valid, verify the token's following claims:

  • exp: expiration. The epoch timestamp when the token expires.
  • nbf: not before. The epoch timestamp when the token becomes valid.
  • (Optional) sub: the Unity Authentication user ID.
  • (Optional) project_id: the Unity project ID.
  • (Optional) jti: the unique token ID.
  • (Optional) iss: the Issuer URL. The expected claim value is https://player-auth.services.api.unity.com.

Refresh the token ID​

If a user's token ID is expired and you want to keep them logged in, you must refresh their token. The token expires in 1 hour. Use the sessionToken from your original authentication response on the /authentication/anonymous or /authentication/external endpoints to receive an updated idToken.

curl -XPOST -H "ProjectId: <projectId>" https://player-auth.services.api.unity.com/v1/authentication/session-token \
-H 'Content-Type: application/json' \
-d '{"sessionToken": "R5pKaP8kEUE2aG...pk08RGC7aM"}'

JSON object response example:

{
    "userId": "T7galGM3T1Bggbb3FfNrzMdivZOG",
    "idToken": "eyJhbGciOiJSUzI1NiIsImt...Lc_RN4mn9Hq2k3tFOX5wukCganFjA",
    "sessionToken": "t1X_x7luG7uVvfTQKp6fd2f...MV6dSZWaJOHNymkmQ-es6qOkHF8",
    "expiresIn": 3599,
    "user": {
        "id": "T7galGM3T1Bggbb3FfNrzMdivZOG",
        "disabled": false,
        "externalIds": []
    }
}

The response includes a different sessionToken that you can use to refresh the token again. Make sure to always use the latest sessionToken returned by the API.

Authorize the user for a specific environment​

By default, Unity Authentication authorizes users to access resources in the default production environment. To authorize a user for a different environment, you must add the header UnityEnvironment to your idToken request.

The idToken request can include /anonymous, /external-token, or /session-token. The value of the header is the environment name. You can check the available environments in a project in UDash.

curl -XPOST -H "ProjectId: <projectId>" -H "UnityEnvironment: <environment name>" https://player-auth.services.api.unity.com/v1/authentication/anonymous

Error codes​

This section describes errors you might receive when making API calls to the Unity Authentication service.

When you receive an error, the response includes the following:

  • status: The HTTP status code.
  • title: A custom error code defined by the authentication service.
  • detail: A message providing more details about the error returned.

If the error code status is in the 400-499 range, the error might be related to the API inputs and coming from the client side.

General errors​

You might receive the following errors when making API calls to the Unity Authentication service:

StatusTitleDetailTroubleshooting
404RESOURCE_NOT_FOUNDN/AMake sure that the projectId header input is correct and that the local project is properly linked to the Unity Organization and Project.
400INVALID_PARAMETERSInvalid environment name providedMake sure that you're calling a valid, existing environment. For more information on environments, refer to the environment documentation.

Sign in and account linking errors with external identity providers​

You might receive the following errors when using the /link and /external-token APIs:

DetailDescriptionTroubleshooting
One of:
  • Token is expired
  • Not valid yet
  • Token issued at claim is in the future
Indicates that the token is invalid.Refresh the external token, then sign in and link the token again.
Invalid audienceIndicates that the application or client ID you have registered with the Unity Authentication service doesn't match the application ID listed in the audience field of your token.Verify that:
  • The application or client ID is in the correct format.
  • The application or client ID matches the ID from your identity provider.
One of:
  • Invalid issuer
  • Invalid signature
Indicates that the ID token wasn't issued by the expected source.Verify:
  • Where the ID token was fetched from.
  • That the Unity Authentication service supports the source.
One of:
  • Malformed token
  • Validation failed
  • Invalid token
Indicates there's an issue with the token input.Verify that:
  • The token type is expected for the identity provider.
  • The token hasn't been manipulated after being fetched from the identity provider.
  • Get a new token.
Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.