Documentation

Support

Multiplay Hosting

Multiplay Hosting

Authentication

Understand the authentication methods available for accessing Multiplay Hosting APIs and services.
Read time 3 minutesLast updated 3 days ago
The methods you must use for authentication vary slightly across the Multiplay Hosting service.
ServiceAuthentication Type
Unity Services Gateway
https://services.api.unity.com
Basic authentication with service account keys.
Unity Game Gateway
https://multiplay.services.api.unity.com
Bearer token from token exchange.
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:
Key IDSecret key
9250f578-9ff1-4b75-afcc-7eca1e94db56
5d7f1a66-f29d-45c8-a6aa-a84242aa805f
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 as
projectID
, 
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 endpointcurl -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 requestcurl -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.