Service Account Authentication

Loading...

Introduction

Service accounts are used for programmatic access to Admin APIs.

These APIs currently support Service Accounts:

• Authentication
• Advertising Management
• Mediation
• Economy
• Cloud Code
• Leaderboards
• Remote Config API
• Resource Configuration
• Player Authentication
• Access

Service Accounts

Prerequisites

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

Step 1: 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.

Step 2: Add Service Account Credentials to your API Requests

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.

Extra step: Use the Token Exchange API

Please ensure to perform this extra-step if you are using one of the following APIs :

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

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

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 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.

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...