Version: en

Player Auth Delegate Token API

warning

This documentation is now deprecated. If you are using Matchmaker Self Serve though UDash, please use the documentation here.

Onboarding#

To use the delegate-token API, the customer needs to be onboarded to the Unity User Authentication Service (UAS). During the matchmaker beta, this should happen automatically.

After onboarding is complete, Multiplay provides the following information to the customer:

client_id
client_secret

note

Because client_secret is used to secure server-to-server API calls, it is sent by using a secure process.

User flow#

There are two types of tokens to be used, namely, the Service Token and the Delegate Token. The Service Token is used to create the Delegate Tokens and is authenticated using the client_id and client_secret provided by Multiplay.

The Delegate Token has two different scopes matchmaking and matchmaking.read. The matchmaking scope provides all-access to the Matchmaking service (Read, Write, Delete), while the matchmaking.read scope provides read-only-access (player access tokens) to the Matchmaking service.

Game Service Definition

A game service is described as an intermediate server/serverless/application that handles certain game related operations. This is to be developed and maintained by the game developer.

Examples include but not limited to, lobby service, authentication server, etc.

Some third-party solutions include, Playfab, GameSparks, Firebase, etc.

Depending on what platform the project intends to support we have 2 recommended flows to interact with the matchmaker. To support platforms like consoles (Xbox, Playstation, Switch, etc.), we recommend the console platform flow. For PC and mobile, the read/write token flow is suitable.

Read/Write Token Flow#

Read/Write user auth flow example image

The flow goes as follows:

Game service creates a Service Token using the client_id and client_secret.
Game service uses the created Service Token to generate a matchmaking scoped Delegate Token.
Game client can request a matchmaking.read scoped Delegate Token (player access token) from the game service, which in turn generates the correct token and passes it on to the game client.
- The game service should make sure to authenticate the client before returning the player access token to prevent unauthorized access.
Game client caches the player access token locally and uses it later on to query the status of a Matchmaking ticket.
Game client can request to create a Matchmaking ticket from the game service.
Game service creates a new ticket (using the Delegate Token with the matchmaking scope) and sets the author of the ticket to match the id of the client that sent the request, and forwards the newly created ticket's id to the game client.
Game client can now use the locally cached player access token along with the ticket id to query for the ticket status.
If the game client wants to stop matchmaking (in case an assignment is received or the player decides to cancel), it can contact the game service to have the ticket deleted by providing their player access token and the ID of the ticket to be deleted.

note

A Delegate Token with the matchmaking scope can create matchmaking tickets on behalf of other users.

A Delegate Token (player access token) with the matchmaking.read scope can only read tickets created by the same user.

caution

The server-to-server token expires every hour. The server side needs to regenerate a new token before the old one expires, ideally 15 minutes before.

Console Platform Flow#

Note for Xbox certification

Details about how to pass certification can be found here.

Console auth flow example image

The flow goes as follows:

The game client authenticates with the platform's authentication service. After a successful login, the client can cache the received token because it will be used throughout the game session.
Game service creates a Service Token using the client_id and client_secret.
Game service uses the created Service Token to generate a matchmaking scoped Delegate Token.
Game client can request to create a Matchmaking ticket from the game service using its platform authentication token.
- The game service must validate the authentication token in order to prevent unauthorized access.
Game service creates a new ticket (using the Delegate Token with the matchmaking scope) and sets the author of the ticket (using the x-on-behalf-of header) to match the id of the client that sent the request, and forwards the newly created ticket's id to the game client.
- The game service should validate the authentication token provided by the game client before creating the ticket.
Game client can now use the locally cached platform authentication token along with the ticket id to query for the ticket status by going through the game service.
If the game client wants to stop matchmaking (in case an assignment is received or the player decides to cancel), it can contact the game service to have the ticket deleted by providing their platform authentication token and the ID of the ticket to be deleted.
- Here the game service should also use the x-on-behalf-of header to make sure a ticket belonging to someone else is not deleted.

Example Scenario#

Let's assume we have 2 players with the following playerids:

Alice's playerid is player-1
Bob's playerid is player-2

Let's also assume we have one game service, that has an id with a value of gameserv

Game Service Flow#

As soon as the game service goes live, it should create a delegate token with the matchmaking scope with the playerid being gameserv. The game-service will need to cache this token and keep it stored for future use.

Every 45 minutes, the game service creates a new matchmaking delegate scoped token with the playerid being gameserv.

Client Login Flow#

Alice starts her game client, and logs into her account. This should trigger the following flow:

Alice's game client sends a request to the game-service to get a matchmaking.read scoped delegate token and passes her playerid as player-1.
The game-service creates a new matchmaking.read scoped delegate token with the playerid set to player-1
The game-service then sends this token to Alice's client.
Alice's game client saves this token in memory.
Every 45 minutes, Alice's game-client automatically sends a request to the game-service to get a new matchmaking.read scoped delegate token with the playerid set to player-1

Client Matchmaking Flow#

Bob now wants to find a multiplayer game, so he clicks on the find game button in the game-client. The following flow is triggered:

Bob's game-client, sends a request to the game-service to create a new matchmaking ticket and passes his playerid as player-2
The game-service, uses the matchmaking scoped delegate token created earlier to create a ticket. Since the ticket we want to create should have the author set to player-2 and the matchmaking token we have has playerid set to gameserv, the game-service uses the X-On-Behalf-Of header with the playerid set to player-2 in the POST request to the Matchmaker.
The Matchmaker creates a ticket with the author set to player-2 since it found the X-On-Behalf-Of header, and passes the ticketID back to the game-service.
The game-service receives the ticketID from the Matchmaker and passes it back to Bob's client.
Bob's client then uses the matchmaking.read scoped token it has saved in memory to poll the Matchmaker for the ticket. (since this token has the playerid set to player-2 , it matches the author of the ticket that was created)

Ticket Delete Flow#

Bob has been waiting for a game for a while and did not find a game, so he decides to cancel the matchmaking request. The following flow is triggered:

Bob clicks on the cancel matchmaking button
Bob's client sends a delete ticket request to the game-service along with the ticketID and his playerid (which is player-2)
The game-service uses the matchmaking delegate token created with the playerid as gameserv and sets the X-On-Behalf-Of header to player-2 and sends the DELETE request to the Matchmaker.
The Matchmaker uses the playerid set in the X-On-Behalf-Of header and matches it to the ticket author. Since both values are set to player-2 the delete request passes and the Matchmaker deletes the ticket.

APIs#

The delegate token API is called by the game service to generate player access tokens. This process requires an access token (Service Token) that authenticates the server-to-server call. This API call should never come from the client side.

API Endpoint: https://api.prd.identity.corp.unity3d.com

Generate a Service Token#

Use POST /oauth2/token to generate the access token for the server-to-server call.

Body: CreateToken
Response: 200 (TokenResponse), 400

Generate a Delegate Token#

Use POST /oauth2/delegate-token to generate delegate token with either a matchmaking or matchmaking.read scope, authorized using the Service Token.

Authorization: Use the access token (Service Token) from the token endpoint.
- For example: Bearer eyJhbGc...25by
- For more information, see the IETF documentation on RFC 6749.
Body: CreateDelegateToken
Response: 200 (DelegateTokenResponse), 400

Contracts#

CreateToken#

{
  "grant_type": "client_credentials",
  "client_id": "2cbb3f35-2233-47a4-ae91-01460c8526df",
  "client_secret": "...",
  "scope": "identity.delegate-token"
}

Field	Description	Type
`grant_type`	The access token grant type. In the delegate token flow, this must be `client_credentials`.	`string`
`client_id`	The OAuth client ID that is generated during customer onboarding.	`string`
`client_secret`	The OAuth client secret that is generated during customer onboarding.	`string`
`scope`	The scope of the server-to-server access token. To ensure that the token can call the delegate-token API, the scope must be `identity.delegate-token`.	`string`

TokenResponse#

{
  "access_token": "eyJhbGc...10aw",
  "scope": "identity.delegate-token",
  "token_type": "bearer",
  "expires_in": 3599,
}

Field	Description	Type
`access_token`	The access token for the server to call the delegate-token API. This is a JWT token that contains the user ID and scope.	`string`
`scope`	The scope that is granted to the access token.	`string`
`token_type`	The response token type. This value is always `bearer`.	`string`
`expires_in`	The duration in seconds in which the access token expires. The default value is 3600 seconds.	`number`

CreateDelegateToken#

{
  "user_id": "142857",
  "scope": "matchmaking"
}

Field	Description	Type
`user_id`	The user ID provided by the game's authentication server. This is the unique identifier for the player.	`string`
`scope`	The scope granted to the access token. Can be *`matchmaking`* or *`matchmaking.read`* only	`string`

DelegateTokenResponse#

{
  "access_token": "eyJhbGc...10aw",
  "expires_in": 3599
}

Field	Description	Type
`access_token`	The access token for the user. This is a JWT token that contains the user ID and scope.	`string`
`expires_in`	The duration in seconds in which the access token expires. The default value is 3600 seconds.	`number`