Service Account Authentication
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:
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
- Open the Unity Dashboard.
- Access the Service Accounts page from the navigation menu (☰) by selecting Projects > Organization / Service Accounts.
- Create a new service account.
- In the Keys section, click
Create key
to generate aKey ID
and aSecret Key
. - 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.