Authentication#

The methods you must use for authentication vary slightly across the Multiplay Hosting service.

Administration API calls that change Multiplay Hosting resources use the Unity Service Gateway.

Game lifecycle API calls, such as allocating and deallocating, use the Unity Game Gateway.

Server Authentication#

Server Authentication is associated with the server, and can be obtained when running on a Multiplay Hosting machine.

It can be used for the Gaming Gateway.

You can retrieve a Multiplay Hosting token in the following ways:

• Scripting API with Authentication package
• Manually through a local request

Scripting API with Authentication package#

Using the following call from the Authentication package:

await ServerAuthenticationService.Instance.SignInFromServerAsync();
var token = ServerAuthenticationService.Instance.AccessToken;

You can also authenticate using a service account:

await ServerAuthenticationService.Instance.SignInWithServiceAccountAsync(apiKeyIdentifier, apiKeySecret);

Refer to service accounts.

Manually obtaining the token#

The token may also be obtain manually through a local request:

curl -X GET http://localhost:8086/v4/token

The request would return a response in the format below:

{"token":"<BEARER_TOKEN>", "error":""}

Service accounts#

All API authentication require service accounts.

If you don't have a service account with a role appropriate for the request you intend to perform, refer to Create a service account.

Service Accounts and authentication are mainly for administrative privileges. Server Authentication are instead of trusted-game services.

Unity Services Gateway#

Use the Unity Services Gateway (USG) to authenticate administrative APIs, such as managing builds, build configurations, fleets, and other Multiplay Hosting resources.

Use basic authentication to authenticate the API call.

Authorization: Basic <base64(keyID:keySecret)>

This means that you create a string that has the KeyID and Secret key separated by a colon, then base64 encode it.

Many HTTP libraries and tools have built-in support for basic authentication. In this case you can use KeyID as the username and Secret key as the password.

Example (list builds)#

Here is an example of creating the header and using it in a curl request to list builds:

You create a string containing Key ID and Secret key (separated by a colon), then base64 encode it.

This gives you the following value:

OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg==

Which can now be used in an authorization header as follows:

curl -X GET 'https://services.api.unity.com/multiplay/builds/v1/projects/<projectID>/environments/<environmentID>/builds \
--header 'Authorization: Basic OTI1MGY1NzgtOWZmMS00Yjc1LWFmY2MtN2VjYTFlOTRkYjU2OjVkN2YxYTY2LWYyOWQtNDVjOC1hNmFhLWE4NDI0MmFhODA1Zg=='

For more information about this endpoint, and parameters used such asprojectID, environmentID refer to the Game Server API documentation.

Unity Game Gateway#

The Unity Game Gateway uses a bearer token for authentication. To get a bearer token, you must first use your service account to request a time limited token from the Unity Game Gateway.

1. Token exchange to retrieve an access token. Refer to Authentication API documentation to learn more.
2. Use the Access Token with bearer authentication to make a request to Unity Game Gateway endpoints
3. The recommended best practice is to reuse the token; however, it expires after one hour, so you must refresh it before it expires.

The Access Token follows is a JWT following RFC 7519 which can be interpreted by any JWT library to extract the exact an expiration time.

Example (list allocations):#

This example shows how to use make a request to the list allocations endpoint. This consists of two steps:

1. Token exchange to retrieve an access token. Refer to Authentication API documentation to learn more.
2. Use the Access Token with bearer authentication to make a request to the list allocations endpoint.

# Get the token from the token exchange endpoint
curl -X POST 'https://services.api.unity.com/auth/v1/token-exchange?projectId=<projectID>&environmentId=<environmentID>' \
--header 'Authorization: Basic  <base64(keyID:keySecret)>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "scopes": []
}'

And receive the response:

{
    "accessToken": <accessToken>
}

The string accessToken string can be used with bearer authentication on subsequent requests to the Unity Game Gateway services. For example to list allocations:

# Make the list allocations request
curl -X GET 'https://multiplay.services.api.unity.com/v1/allocations/projects/<projectID>/environments/<environmentID>/fleets/<fleetID>/allocations \
--header 'Authorization: Bearer <accessToken>'

For more information about this endpoint, and parameters used such as projectID, environmentID, and fleetID, refer to the Game Server API documentation.