Authentication for matchmaker

Use authentication in Matchmaker to securely identify and authorize players.

Read time 2 minutes

Last updated 22 days ago

There are two ways to authenticate in Matchmaker:

Player authentication
Service Account authentication

Player authentication

Player authentication uses Unity Authentication to enable player-driven matchmaking so that a game client can contact the Matchmaker service to create a ticket.

Make sure to initialize the Authentication service and sign in before making any calls using the Matchmaker SDK.

There are multiple ways to sign in. The simplest method is to use anonymous sign-in.

Multiplayer Services SDK implementation

In the Multiplayer Services SDK (

com.unity.services.multiplayer

), player authentication is a hard requirement, not an optional path.

MultiplayerInitializer

registers

IAccessToken

(from

Unity.Services.Authentication.Internal

) as a required dependency for the entire package, so the SDK can't initialize matchmaking without it.

Every client-facing matchmaking call

MatchmakeSessionAsync

CreateTicketAsync

GetTicketAsync

DeleteTicketAsync

, and

GetMatchmakingResultsAsync

internally calls a guard method (

EnsureSignedIn()

WrappedMatchmakerService

) that checks

IAccessToken.AccessToken

. If the player hasn't signed in through the Authentication service, the call throws:


MatchmakerServiceException(Unauthorized, "You are not signed in to the Authentication Service. Please sign in.")

In practice, this means calling

AuthenticationService.Instance.SignInAnonymouslyAsync()

(or another sign-in method) before any matchmaking call, as shown in the SDK's own examples.

Service Account authentication

Use Service Account authentication when a backend service creates a matchmaking ticket on behalf of a game client. This is useful when it's required to add server authoritative data to a matchmaking ticket, like a skill value, for example.

To create a Service Account, follow these instructions.

To use the Service Account in Matchmaker, follow those steps.

Here's an example of a typical service-to-service authentication flow:

The client performs an anonymous authentication as described in Player authentication.
The client calls a custom backend server with the
```
PlayerId
```
as the parameter.

The custom backend calls the ticket creation route with the

impersonate-user-id

header set to the

PlayerId

value:


curl --location --request POST 'https://matchmaker.services.api.unity.com/v2/tickets' \--header 'Content-Type: application/json' \--header 'Authorization: {{SERVICE-ACCOUNT-TOKEN}}' \--header 'impersonated-user-id: {{PLAYER-ID}}' \--data-raw '{ "players": [ { "id": "{{PLAYER-ID}}","customData": { "Skill": {{ENRICHED-DATA}} } } ] }'

The custom backend sends the ticket ID back to the client.
The client polls the ticket status using the client SDK.

Documentation

Development

User Acquisition

Monetization

Industry