Service Account Authentication

Loading...

Introduction

Service accounts are used for programmatic access to Admin APIs.

There are two classes of APIs that support Service Accounts. Those that support direct Service Account authentication and those that additionally require a stateless token.

These APIs currently support Service Accounts directly:

• Authentication
• Advertising Management
• Mediation
• Economy
• Cloud Code
• Leaderboards
• Remote Config API
• User Generated Content
• Multiplay
• Player Authentication
• Access

These APIs additionally require a stateless token:

• Cloud Save
• Economy
• Cloud Code
• Leaderboards
• Lobby
• Matchmaker
• Friends
• Multiplay Game Server Lifecycle

Service Accounts

Prerequisites

Ensure you are an Organization Owner or you will not be able to manage service accounts or access your API keys.

Creating a Service Account

1. Open the Unity Dashboard.
2. Access the Service Accounts page from the navigation menu (☰) by selecting Projects > Organization / Service Accounts.
3. Create a new service account.
4. In the Keys section, click Create key to generate a Key ID and a Secret Key.
5. Select the suitable roles to allow access to the corresponding API endpoints. To know which roles are applicable, please refer to the service's API documentation.

There are two types of roles: 1) Project roles 2) Organization roles

Project roles grant access to project-level data, which includes APIs that only apply to individual projects you choose. Organization roles will grant access to organization-level data that apply to all projects in your organization.

At this point you can either use the service account credentials to call an API or exchange for a stateless authentication token.

Using Service Account Credentials

API requests are authenticated with the Authorization HTTP header. Such as:

curl -H "Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS>" \
https://services.api.unity.com/<ENDPOINT>

Where <SERVICE_ACCOUNT_CREDENTIALS> are formed by Base64 encoding the string <KEY_ID>:<SECRET_KEY>. For example, given the following:

• Key ID: 7e0f1152-e0dd-4b14-8e37-04cab07efeb0
• Secret Key: NKxoRp2m2w3e9gzJfssNQnTfypFgtJn7

Then the concatenated string for the Authorization header would look as follows:

7e0f1152-e0dd-4b14-8e37-04cab07efeb0:NKxoRp2m2w3e9gzJfssNQnTfypFgtJn7

Here's a tip : on an Unix terminal, you can Base64 encode the string via:

echo -n "7e0f1152-e0dd-4b14-8e37-04cab07efeb0:NKxoRp2m2w3e9gzJfssNQnTfypFgtJn7" | base64

Which will result in: N2UwZjExNTItZTBkZC00YjE0LThlMzctMDRjYWIwN2VmZWIwOk5LeG9ScDJtMnczZTlnekpmc3NOUW5UZnlwRmd0Sm43.

Now, replace this value to the placeholder <SERVICE_ACCOUNT_CREDENTIALS>. For example:

curl -H "Authorization: Basic N2UwZjExNTItZTBkZC00YjE0LThlMzctMDRjYWIwN2VmZWIwOk5LeG9ScDJtMnczZTlnekpmc3NOUW5UZnlwRmd0Sm43" \
https://services.api.unity.com/<ENDPOINT>

For most APIs, the instructions above will be all you need to authenticate to the API.

However, in very specific cases, you might need to use the next Token Exchange API step described below.

Using stateless tokens

Some APIs require the a stateless token for their authentication. This can be done using the Token Exchange API.

Ensure you have created a service account and made note of the Key ID & Secret ID

The Token Exchange API accepts the Key ID and Secret Key as inputs and returns a stateless token that can then be used for authenticating against certain APIs.

The stateless token has a limited lifespan and once it expires a new token can be refreshed using the Token Exchange API.

How to use it

Call the Token Exchange API by sending the Key ID and Secret Key as the authorization in the request.

See using service account credentials for details on how to encode the contents of the Authorization header.

curl -X POST -H "Authorization: Basic N2UwZjExNTItZTBkZC00YjE0LThlMzctMDRjYWIwN2VmZWIwOk5LeG9ScDJtMnczZTlnekpmc3NOUW5UZnlwRmd0Sm43" https://services.api.unity.com/auth/v1/token-exchange?projectId=<PROJECT_ID>&environmentId=<ENVIRONMENT_ID>

Returns you a response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTYyMzkwMjJ9.tbDepxpstvGdW8TC3G8zg4B6rUYAOvfzdceoH48wgRQ",
}

Now you can use the accessToken from the response to call APIs in the context of the given Project ID and / or Environment ID

curl -H "Authorization: Bearer <STATELESS_ACCESS_TOKEN>" \
https://services.api.unity.com/<ENDPOINT>

See the Token Exchange API documentation for detailed usage.

Refreshing the token

The format of the returned Stateless Access Token is a standard RFC 7519 JSON Web Token. The token contains an exp field in the token body after which the Stateless Access Token is not valid anymore.

The value of the exp field is a numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds.

Clients using the Token Exchange API must refresh token when it has expired by calling the Token Exchange API with the original Key ID and Secret Key pair.

Exchanging a new token does not invalidate the previous tokens so refreshing can be done in advance before the previous token has expired.

Available roles

Loading...