Documentation

Development

User Acquisition

Monetization

Industry

Authentication

Unity SDK

Admin API

Client API

Open Unity Dashboard

Authentication

LiveOps
​
​
Authentication
  • Overview
  • Get started
  • Concepts
  • Tutorials
    • Anonymous sign-in
    • Google Play Games
    • Apple Game Center
    • Steam
    • Facebook
    • Unity Player Accounts
    • Oculus
    • Username and Password
    • Code-Link
    • Google
    • Apple
    • Custom OpenID Connect
    • Custom ID
  • Reference
  • Privacy and consent
  1. Unity Authentication

Custom ID sign-in

Provide a Custom ID sign-in option to enable players to authenticate using your custom identity system in your game.
Read time 4 minutes
Last updated 9 months ago
Minimum SDK version: 3.1.0
If you already have an existing player management system that creates player IDs, you can use the Custom ID provider to link the identities.
The Custom ID providers works by having game clients make requests to your game backend. Your backend uses Service Account credentials to generate tokens for the players with custom IDs and returns it to them for use with UGS services.
Since the Unity Authentication service is not in control of the provided player IDs, it needs to rely on a server-authoritative backend and cannot allow game clients to request their own tokens.
This article guides you through the following scenarios to set up authentication for players in your game with a Custom ID provider:
  • Set up Custom ID Provider sign-in.
  • Sign in a returning user or create a new user.

Set up a Custom ID Sign In

  1. Add Custom ID as an ID provider for Unity:
    1. In the Unity Editor select Services > Authentication > Configure from the navigation menu.
    2. Set ID Providers to Custom ID, then select Add.
  2. Create a Service Account and add project role Player Authentication Token Issuer. These credentials will be used by your backend to make requests to the Unity Authentication service.

Client-side setup

Together with the server side sign in set up further below, an access token has to be retrieved from your backend and processed with the 
AuthenticationService
:
ProcessAuthenticationTokens
is used to process Unity Authentication Service Tokens and makes them available to other UGS SDKs integrated into the game that require the player to be authenticated. This results in the player being effectively signed in using the tokens provided.
You should call 
ProcessAuthenticationTokens
with both the access token and the session token. The Unity Authentication SDK refreshes the access token before it expires to keep the player's session active. Refer to the page on session management for more details.
Alternatively you can call 
ProcessAuthenticationTokens
with only the access token. However since access tokens expire after 1 hour you must manually refresh the access token and call 
ProcessAuthenticationTokens
with the new access token.
using Unity.Services.Authentication;async Task SignInUserWithCustomID(){    try    {        // Check if a cached player already exists by checking if the session token exists        if (AuthenticationService.Instance.SessionTokenExists)        {            // This call will sign in the cached player.            await AuthenticationService.Instance.SignInAnonymouslyAsync();            Debug.Log("Cached user sign in succeeded!");        }        else        {            var userTokens = ; // Fetch the user tokens using method calls to your backend            AuthenticationService.Instance.ProcessAuthenticationTokens(userTokens.AccessToken, userTokens.SessionToken);        }        // Shows how to get the playerID        Debug.Log($"PlayerID: {AuthenticationService.Instance.PlayerId}");    }    catch (AuthenticationException ex)    {        // Compare error code to AuthenticationErrorCodes        // Notify the player with the proper error message        Debug.LogException(ex);    }    catch (RequestFailedException ex)    {        // Compare error code to CommonErrorCodes        // Notify the player with the proper error message        Debug.LogException(ex);    }    catch (Exception ex) {        // Handle exceptions from your method call        Debug.LogException(ex);    }}
Note that the sample code is a method only, not a class.
The access and session tokens need to be retrieved from your backend. Refer to the Server-side setup below for more information on that.

Server-side setup

During the player sign-in process on your backend, each player is signed up with Unity Authentication service using their custom ID and granted a 
accessToken
and 
sessionToken
. Your backend uses the Service Account credentials to perform the requests to sign up the players with Unity Authentication.
  1. Call the Token Exchange API to retrieve a stateless token.
  2. Call the Sign In With Custom ID API:
curl --location 'https://player-auth.services.api.unity.com/v1/projects/<PROJECT_ID>/authentication/server/custom-id' \--header 'Content-Type: application/json' \--header 'UnityEnvironment: <ENVIRONMENT_NAME>' \--header 'Authorization: Bearer <STATELESS_TOKEN' \--data '{    "externalId": "YOUR_CUSTOM_PLAYER_ID"}'
The response of this request will contain an 
idToken
and a 
sessionToken
that you have to return to the game client for initializing the 
AuthenticationService
. The 
idToken
can be used as the 
accessToken
in this context.

Linking an existing player

If the player already has a Unity Authentication account, they can be linked by providing the existing access token to the Custom ID sign-in request. The access token will need to be provided either by the player in their request to your backend, or requested by your backend if it knows which existng Unity player ID they want to be linked to:
curl --location 'https://player-auth.services.api.unity.com/v1/projects/<PROJECT_ID>/authentication/server/custom-id' \--header 'Content-Type: application/json' \--header 'UnityEnvironment: <ENVIRONMENT_NAME>' \--header 'Authorization: Bearer <STATELESS_TOKEN' \--data '{    "externalId": "YOUR_CUSTOM_PLAYER_ID"    "accessToken": "EXISTING_PLAYER_ACCESS_TOKEN"}'
Copyright © 2026 Unity Technologies
LegalPrivacy PolicyCookiesDocumentation Terms of UseDo Not Sell or Share My Personal InformationYour Privacy Choices (Cookie Settings)

"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.

Some pages are machine-translated for convenience, and may contain inaccuracies. In the event of conflicting information, the English version is authoritative.

  • On this page

    • Minimum SDK version: 3.1.0

    • Set up a Custom ID Sign In

    • Client-side setup

    • Server-side setup

    • Linking an existing player

Report a problem with this page
​
​