Service accounts are used for programmatic access to Admin APIs.
These APIs currently support Service Accounts:
- Advertising Management
- Cloud Code
- Remote Config API
- Multiplay Resource Configuration
- Player Authentication
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
- 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 keyto generate a
Key IDand a
- 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>" \
<SERVICE_ACCOUNT_CREDENTIALS> are formed by Base64 encoding the
<KEY_ID>:<SECRET_KEY>. For example, given the following:
- Key ID:
- Secret Key:
Then the concatenated string for the Authorization header would look as follows:
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:
Now, replace this value to the placeholder
<SERVICE_ACCOUNT_CREDENTIALS>. For example:
curl -H "Authorization: Basic N2UwZjExNTItZTBkZC00YjE0LThlMzctMDRjYWIwN2VmZWIwOk5LeG9ScDJtMnczZTlnekpmc3NOUW5UZnlwRmd0Sm43" \
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 :
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:
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>" \
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.