Skip to main content

Client Authentication

Loading...

Introduction​

Client APIs are endpoints that allow you to reach Unity Services as the player of a Unity project. These endpoints will typically be called in the application (i.e. in game) following the action of a player.

Unity Authentication is a service that provides both anonymous and platform-specific authentication solutions for Client APIs. Unless otherwise specified in a Client API's documentation, please use Unity Authentication as outlined below to authenticate with 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 is 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 are 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 are responsible for verifying that the id token is valid. For more information on how to verify the id token, please 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. Please refer to the

Refreshing the idToken section to learn how to do that.

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

Type 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. In other words, 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.

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.

Documentation for the following external identity providers can be found in this section

Google
Google Play Games
Apple
Apple Game Center
Facebook
Steam
Oculus
Custom OpenID Connect (OIDC)

Custom OpenID Connect (OIDC)​

Custom OpenID Connect (OIDC) allows you to configure a custom, OIDC-compliant identity provider with Unity Authentication. There are limitations that we enforce, which you can learn about in the setup steps section.

We currently only support Id Token based sign-in. For more information about this, please read the OpenID specs.

Anonymous Authentication​

Anonymous authentication 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.

The following example shows how to set up the ability for players to sign in to your game anonymously and get an access token.

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.

Create an Anonymous Player​

Create an anonymous player Id by calling the API below:

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

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": []
    }
}

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>

If you want to authorize the player for a specific environment, please check the Authorizing for a Specific Environment section.

The idToken expires in 1 hour and will need to be refreshed. The sessionToken can be used to do this. Please read

Refreshing the Id token for more information.

Platform-Specific Authentication​

Platform-specific authentication (also called third-party authentication or external authentication) is where you leverage third party identity providers to authenticate players. You must create an identity provider configuration via these setup steps so that Unity Authentication can validate the third party access or identity token. Platform-specific authentication enables new use cases, including:

  • providing a consistent login method, in case the player is logged out
  • allowing players to access the same account across different devices

Compatibility List​

Unity Authentication currently supports the following Platform-Specific Identity Providers:

Facebook Limited Login is supported as well, and requires no additional configuration for Unity Authentication beyond following Facebook's setup steps. This login method is only available on iOS. For more information, please refer to Facebook's documentation.

Setup Steps​

You can add and configure the identity providers via the Editor Settings in the Unity Editor (if you have the Unity Authentication SDK) or the Unity Dashboard. For steps to configure via the Unity Editor, please refer here. Otherwise, continue reading to see the steps to configure via the Unity Dashboard.

Facebook​

These steps assume you have registered and properly configured an Application with Facebook.

  1. Gather the App Id and App Secret from Facebook. For more information about this, please refer to Facebook's documentation.
  2. Log into the Unity Dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select Facebook from the drop-down.
  7. In the input fields, type in the App Id and App Secret.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

Note: We currently support the ‘Consumer’ app type. For more information, please refer to Facebook's documentation.

Apple​

These steps assume you have registered and properly configured an Application with Apple.

  1. Gather the Client Id from Apple. For more information, please refer to Apple's documentation.
  2. Log into the Unity Dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select Sign in with Apple from the drop-down.
  7. In the input fields, type in the App Id.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

Apple Game Center​

These steps assume you have registered and properly configured an Application with Apple Game Center.

  1. Gather the Bundle Id from Apple Game Center. For more information, please refer to Apple's documentation.
  2. Log into the Unity Gaming Services dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select Apple Game Center from the drop-down.
  7. In the input fields, type in the Bundle Id.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

Steam​

These steps assume you have registered and properly configured an Application with Valve.

  1. Gather the App Id and Key from Valve. For more information, please refer to Valve's documentation.
  2. Log into the Unity Dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select Steam from the drop-down.
  7. In the input fields, type in the App Id and Key.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

Google​

These steps assume you have registered and properly configured an Application with Google.

  1. Gather the Client Id from Google. For more information, please refer to Google's documentation.
  2. Log into the Unity Dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select Google from the drop-down.
  7. In the input fields, type in the Client Id.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

Google Play Games​

These steps assume you have registered and properly configured an Application with Google.

  1. Gather the Client Id and Client Secret from Google. For more information, please refer to Google's documentation.
  2. Log into the Unity Dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select Google Play Games from the drop-down.
  7. In the input fields, type in the Client Id and Client Secret.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

Oculus​

These steps assume you have registered and properly configured an Application with Oculus.

  1. Gather the App Id and App Secret from Oculus. For more information, please refer to Oculus's documentation.
  2. Log into the Unity Dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select Oculus from the drop-down.
  7. In the input fields, type in the App Id and App Secret.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

Custom OpenID Connect (OIDC)​

These steps assume you have registered and properly configured an Application with the Custom OpenID Connect (OIDC) provider.

  1. Gather the Client Id and Issuer URL from the Custom OIDC provider. For more information, please refer to the OpenID Connect Specification.
  2. Log into the Unity Dashboard.
  3. Make sure the project selected is the correct one.
  4. On the left side of the page, select the LiveOps button.
  5. Under the LiveOps tab, click the Authentication drop-down and click Identity Providers.
  6. On the right side, click Add Identity Provider, and select OpenID Connect from the drop-down.
  7. In the input fields, type in the desired name, Client Id, and Issuer URL.
  8. On the bottom left side of the pop-up, check the Enable Identity Provider checkbox.
  9. Click Add Identity Provider.

For the identity provider type name, it is a custom name of your choosing. There are limitations to the naming conventions:

  • Must start with oidc-
  • Maximum length of 20 (including the oidc- prefix)
  • Provider string can only contain the following ranges/characters:
  • a-z lowercase characters
  • 0-9 number characters
  • other characters allowed: [".", "-", "_""]

In addition to following the OpenID connect spec, there are several other limitations that we enforce on the issuer:

  • The issuer URL must be the https protocol scheme.
  • The issuer URL cannot be more than 100 characters long.
  • The openid-configuration response cannot be larger than 200000 bytes.
  • The jwks response cannot be larger than 200000 bytes.

Platform-Specific Authentication APIs​

There are three APIs Unity Authentication provides which are tied to Platform-Specific Authentication. They are:

  • External Token
  • Link
  • Unlink

When the end player logs into their Platform-specific identity provider, you should have access to their access or id token. Pass the player's Platform-specific identity provider access token into one of these APIs. For more information on how to gather these tokens, please refer to each Platform-specific Authentication provider's respective documentation.

For Custom OpenID Connect (OIDC), Unity Authentication only supports the Id Token as a token input. For more information about the id token, please refer to the OpenID specs.

API Inputs​

All of these APIs require a Project Id and an Id Provider as inputs. The Project Id will be sent as a header. For steps on how to find your Unity Project Id please refer to this section.

The Identity Provider type will be sent as part of the API path. When calling the Platform-specific Authentication APIs use these constant values as inputs:

  • Facebook: facebook.com
  • Apple: apple.com
  • Steam: steampowered.com
  • Google: google.com
  • Google Play Games: google-play-games
  • Oculus: oculus
  • Apple Game Center: apple-game-center

For Custom OpenID Connect (OIDC), the API input is the name configured in the setup steps.

For example:

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

External Token​

The external token API is used to create or log in a Unity Authentication Account with a Third Party Identity.

It can be used when:

  • the player is currently not logged into Unity Authentication
  • the player has successfully logged into their Third-Party Authentication provider.
  • you want to log in the player with their third party access token

This is a valid example API call:

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>"
}'

The API will respond with a JSON object. For 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>"
            }
        ]
    }
}

Find the idToken field in the JSON object. This will be used for future requests where you need to take action on the player.

At this point, a new player has been created on Unity Authentication and linked to the external identity specified on the access token.

If you want to authorize the player for a specific environment, please check the Authorizing for a Specific Environment section.

Oculus API Inputs

For Oculus sign in, we require the player Id and a nonce as an input. The request body will look like this:

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

For more information, please read the Oculus documentation.

Apple Game Center API Inputs

For Apple Game Center sign in, we require these values from Apple:

  • Signature
  • Team Player Id
  • Salt
  • Timestamp
  • Public Key Url

The token field in the API request will contain the Signature value. The request body will look like this:

{
    "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>"
    }
}

NOTE: For the Signature and Salt, we require that the values be Base64 encoded string values of the raw value you obtain from Apple.

NOTE: For Unity Authentication, the timestamp input is only valid for 10 minutes for security reasons. Before calling the External Token API or Link API endpoint, please call Apple's FetchItems API to receive fresh inputs. After a single successful call to External Token API or Link API, there is no need to call these APIs anymore.

For more information, please read the Apple Game Center documentation.

Sign In Only

By default, the External Token API will create a new player on Unity Authentication if one does not already exist. If you do not want to create a new Unity Authentication account, then you can set the signInOnly flag to true. For example:

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
}'

If an account does not exist, then this request will fail and no new account will be created.

The link API is used to link a Unity Authentication Account with a third party identity.

It can be used when:

  • the player is currently logged into Unity Authentication
  • the player has successfully logged into their Third Party Authentication provider.
  • you want to link the Unity Authentication player with a third party identity that is not currently linked.

The player's Unity Authentication Id Token is used to authorize actions on their account. In order to get the Id Token, make sure to save the Id Token from a previous Authentication response.

This is a valid example API call:

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

The API will respond with a JSON object. For example:

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

At this point, the external identity is now linked to the Unity Authentication player.

Force Link

Unity Authentication currently only allows an external identity to be linked to a single Unity Authentication player. By default, if a different Unity Authentication player is already linked to the external identity specified in the request, then the Link API request will fail.

Force link allows you to unlink the external id from the already linked player, and link the external id to a different player. If you want to force link the external identity to a different Unity Authentication player, then set the forceLink flag to true.

For example:

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

The unlink API is used to unlink a Unity Authentication Account from a third party identity.

It can be used when:

  • the player is currently logged into Unity Authentication
  • you want to unlink the Unity Authentication player from a third party identity.

Instead of the Platform-specific Identity Provider's Access Token, you will need the External Id of the player. This information is returned in the externalIds section of the External Token and Link API responses.

The player's Unity Authentication Id Token is used to authorize actions on their account. In order to get the Id Token, make sure to save the Id Token from a previous Authentication response.

This is a valid example API call:

curl --location --request POST 'https://player-auth.services.api.unity.com/v1/authentication/unlink/<Id Provider>' \
--header 'Content-Type: application/json' \
--header 'ProjectId: <projectId>' \
--header 'Authorization: Bearer <Id Token from Unity Authentication>' \
--data-raw '{
    "externalId": "<Third Party External Id>"
}'

The API will respond with a JSON object. For example:

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

At this point, the external identity is now unlinked from the Unity Authentication player.

Player Management APIs​

Clients also have the ability to perform operations on the Unity Authentication player.

Get Player​

The Get Player API is used to check information about the player.

It can be used when:

  • the player is currently logged into Unity Authentication
  • you need information about the player

This is a valid example API call:

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>'

The API will respond with a JSON object. For example:

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

Delete Player​

The Delete Player API is used to delete the player.

It can be used when:

  • the player is currently logged into Unity Authentication
  • you need to delete the player

This is a valid example API call:

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>'

The API will respond with an empty JSON object. For example:

{}

The player is now deleted from Unity Authentication, and cannot be referenced again.

Validating the idToken​

The player's Id token must be valid for a logged in player. The Id token is a JWT that can be verified. These are the high level steps to validate the Id token:

  1. Fetch the JSON Web Key Set (JWKS) from Unity Authentication. The JWKS contains the public key used to validate the tokens.
  2. Verify the signature of the Id token. This step makes sure the token is signed by the Unity Authentication server, and to make sure the claims are not modified.
  3. Decode the base64url-encoded Id token.
  4. Verify the claims are valid.

For more information about JWTs, please read this RFC 7519 JWT overview.

Fetching the JWKS​

The JWKS for Unity Authentication is available from the following endpoint:

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

The output is a standard JWKS. An example response is this:

{
    "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"
        }
    ]
}

We recommend that you refresh the JWKS every 8 hours. If the Id Token's key id is not found in the cached JWKS, then we recommend that you fetch the JWKS once at that moment.

Please do not attempt to refresh the JWKS too often, as it will result in a rate limit being enforced. For more information on the enforced limit, please read here.

Verifying Claims​

There are a few standard claims you need to verify to make sure the token is valid. Key claims to validate are:

  • exp: Expiration - The epoch timestamp when the token expires.
  • nbf: Not Before - The epoch timestamp when the token starts to be valid.

Other claims that may be validated are:

  • sub: It is the Unity Authentication player Id.
  • project_id: The Unity project Id.
  • jti: The unique Id of the token itself.
  • iss: This is the Issuer URL. The expected claim value is https://player-auth.services.api.unity.com.

Refreshing the idToken​

The player's idTokenexpires in 1 hour. Before the idToken expires, use the sessionToken returned in your original authentication response on the /authentication/anonymous or /authentication/external endpoints to get an updated idToken. To make sure the player's idToken is refreshed in time, please start the refresh five minutes before the expiration to allow some buffer time and a potential retry.

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"}'

The API will again respond with a JSON object. Find the updated idToken and sessionToken fields. For example:

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

In the response, you will receive another sessionToken, which you can re-use to refresh the token again. Please always use the latest sessionToken returned by the API to refresh the idToken.

If you want to authorize the player for a specific environment, please check the Authorizing for a Specific Environment section.

Authorizing for a Specific Environment​

By default, Unity Authentication will authorize players to access resources in the default environment, which is production. However, you have the option to authorize the end player for a specific environment. You will need to add the header UnityEnvironment into the requests that you get an idToken from, which include /anonymous, /external-token, and /session-token. The value of the header is the environment name. You can check the available environments in a project in UDash. For example:

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

Common Errors​

This section describes common errors that you may encounter when making API calls to the Unity Authentication service.

The returned errors are in the RFC 7808 format:

  • status: This is the http status code.
  • title: This is a custom error code defined by the Authentication Service.
  • detail: This is a human readable message that may include details about the issue. This field is intended for debugging purposes during development.

For error code paths, only determine the subsequent action using the status or title fields. Do not use the detail field to determine subsequent code paths.

If the status is in the 400-499 range, the error might be resulting from the client. There is a decent chance it is related to the API inputs.

By looking at the detail field you can find further description of the issue.

General Errors​

These are some general errors that may appear when using any of the Unity Authentication APIs.

status: 404
title: RESOURCE_NOT_FOUND

Please double check if the projectId header input is correct. Please also double check that the local project is properly linked to the Unity Organization and Project.

status: 400
title: INVALID_PARAMETERS
detail: invalid environment name provided

Please double check that you are calling a valid, existing Environment. For more information about Environments, please read these Environment docs.

Errors from Signing In and Account Linking with Platform-Specific Providers​

These errors may appear when using the /link and /external-token Unity Authentication APIs.

Below you can find the common errors by description and the steps you can take to try and fix them.

For all of these issues, you can check the Identity Providers Compatibility List and Identity Providers Setup Steps sections for more details about specific Identity Providers.

Detail: "token is expired"
        "not valid yet"
        "token issued at claim is in the future"

Description: These errors indicate that the token is not valid at this moment, whether it's because the token was issued for a time period later or earlier than now.

Steps to fix:

  • Refresh the external token
  • Sign in or link again after refreshing the external token.
Detail: "invalid audience"

Description: This usually applies to Id Token based authentication. It indicates there is a mismatch between the application or client id you registered with Unity Authentication and the application id listed on the token, which is usually in the audience field.

Steps to fix:

  • Check the Identity Providers section for the relevant id provider and take note of the expected format for the application or client id.
  • Verify if the application or client id you registered within Unity Authentication in the Editor Settings page or Unity Dashboard matches the one from your identity provider.

Note: Sometimes the Id Provider provides multiple application ids in different formats, and inputting the incorrect type will lead to this error.

Detail: "invalid issuer"
        "invalid signature"

Description: These errors indicate that the Id token was not issued by the expected source.

Steps to fix:

  • Verify how and where the Id token was fetched from, and if it matches what Unity Authentication supports.
Detail: "malformed token"
        "validation failed"
        "invalid token"

Description: This indicates there was some issue with the token input.

Steps to Fix:

  • Verify if the token is the expected token type for the Id Provider.
  • Verify if the token is manipulated in any way after fetching it from the Id Provider. Generally speaking, tokens should not be manipulated.
  • Get a new token.
Unity logo Documentation
Copyright © 2023 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.