Authentication#

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

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

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

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.

Unity Services Gateway#

Use the Unity Services Gateway (USG) to authenticate administrative APIs, such as managing builds, build configurations, fleets, and other Game Server 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.