# Admin authentication

> Learn how to authenticate admin APIs using service accounts and stateless tokens.

Admin APIs allow you to access and configure Unity Services as an administrator. To authenticate admin APIs, you must create and use service accounts.

## Supported APIs

Some APIs directly support service account authentication, while others require an additional stateless token.

These APIs directly support service accounts:

* [Authentication](https://services.docs.unity.com/auth/v2)
* [Advertising Management](https://services.docs.unity.com/advertise/v1)
* [Advertising Statistics](https://services.docs.unity.com/statistics/v2)
* [Assets Manager](https://services.docs.unity.com/assets-manager/v1)
* [Assets External Providers](https://services.docs.unity.com/assets-manager-external/v1)
* [Collaboration](https://services.docs.unity.com/collaboration/v1)
* [Application Linking](https://services.docs.unity.com/app-linking/v1)
* [Annotations](https://services.docs.unity.com/annotations/v1)
* [Presence](https://services.docs.unity.com/presence/v1)
* [Mediation](https://services.docs.unity.com/mediation/v1)
* [Cloud Save](https://services.docs.unity.com/cloud-save-admin/v1)
* [Economy](https://services.docs.unity.com/economy-admin/v2)
* [Triggers](https://services.docs.unity.com/triggers-admin/v1)
* [Scheduler](https://services.docs.unity.com/scheduler-admin/v1)
* [Cloud Code](https://services.docs.unity.com/cloud-code-admin/v1)
* [Leaderboards](https://services.docs.unity.com/leaderboards-admin/v1)
* [Matchmaker](https://services.docs.unity.com/matchmaker-admin/v3)
* [Session Observability](https://services.docs.unity.com/session-observability/v1)
* [Remote Config](https://services.docs.unity.com/remote-config-admin/v1)
* [SCIM](https://services.docs.unity.com/scim/v2)
* [Content Delivery Management](https://services.docs.unity.com/content-delivery-management/v1)
* [Player Authentication](https://services.docs.unity.com/player-auth-admin/v1)
* [Resource Policy](https://services.docs.unity.com/access-resource-policy/v1)
* [Access (deprecated)](https://services.docs.unity.com/access/v1)
* [Safe Voice](https://services.docs.unity.com/safevoice/v1)
* [Vivox Moderation](https://services.docs.unity.com/vivox-moderation/v1)
* [Moderation](https://services.docs.unity.com/moderation/v1)
* [Text Evidence Management](https://services.docs.unity.com/vivox-text-evidence-management/v1)
* [Realm](https://services.docs.unity.com/realm-admin/v1)
* [Server Side Recording](https://services.docs.unity.com/ssr/v2)
* [Vivox Safe Text](https://services.docs.unity.com/vivox-safe-text/v1)
* [Storage](https://services.docs.unity.com/storage/v1)
* [Observability](https://services.docs.unity.com/observability/v1)
* [Instance Metadata](https://services.docs.unity.com/data-streaming/v1)
* [Workflow Engine](https://services.docs.unity.com/workflow-engine/v1)

These APIs require an additional stateless token:

* [Cloud Save](https://services.docs.unity.com/cloud-save/v1)
* [Economy](https://services.docs.unity.com/economy/v2)
* [Cloud Code](https://services.docs.unity.com/cloud-code/v1)
* [Leaderboards](https://services.docs.unity.com/leaderboards/v1)
* [Lobby](https://services.docs.unity.com/lobby/v1)
* [Matchmaker](https://services.docs.unity.com/matchmaker/v2)
* [Multiplay Game Server Lifecycle](https://services.docs.unity.com/multiplay-gameserver/v1)
* [Friends](https://services.docs.unity.com/friends/v1)
* [Player Names](https://services.docs.unity.com/player-names/v1)

## Prerequisites

Before you use service accounts, make sure you are an [Organization Owner or Organization Manager](/cloud/organizations/roles-and-permissions.md).

## Create a service account

To create a service account, follow these steps:

1. In the [Unity Dashboard](https://cloud.unity.com), open the Account menu and select **Manage organization**.
2. In the Administration menu, select **Service Accounts**.
3. Select **Create service account** to create a new account.
4. In the **Keys** section, select **Create key** to generate a key ID and a secret key.
5. Add a role to your service account to allow access to API endpoints.
   * Select **Add organization role** to grant access to organization-level data that applies to all projects in your organization.
   * Select **Add project role** to grant access to project-level data that applies to individual projects.

You can now use either your service account credentials or a stateless authentication token to authenticate and call an API.

## Authenticate an API using service account credentials

To authenticate an API using your service account credentials, open a terminal and enter the following authorization HTTP header:

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

The `<SERVICE_ACCOUNT_CREDENTIALS>` is created by Base64 encoding the string `<KEY_ID>:<SECRET_KEY>`. It uses the key ID and secret key you generated when you
created a service account.

For example, if your key ID is `7e0f1152-e0dd-4b14-8e37-04cab07efeb0` and your secret key is `NKxoRp2m2w3e9gzJfssNQnTfypFgtJn7`, your header will be
`7e0f1152-e0dd-4b14-8e37-04cab07efeb0:NKxoRp2m2w3e9gzJfssNQnTfypFgtJn7`.

### Authenticate an API with the Unix terminal

> **Important:**
>
> You must Base64 encode the key string before authenticating an API with the Unix terminal.

If you're using a Unix terminal, follow these steps:

1. Enter a command to Base64 encode the key string.

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

2. Replace `<SERVICE_ACCOUNT_CREDENTIALS>` with the output from the previous command.

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

You have now authenticated your API.

## Authenticate an API using a stateless token

To authenticate an API using a stateless token, follow these steps:

1. Call the [Token Exchange API](https://services.docs.unity.com/auth/v1). Make sure to send your key ID and your secret key as the authorization in the request.

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

As a response, you receive an `accessToken`.

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

2. Use the `accessToken` to call APIs in the context of the project ID and/or environment ID you specified earlier.

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

### Refresh your stateless token

The stateless access token you receive after calling the Token Exchange API includes an `exp` field which determines the token's lifespan. If your token expires,
you can refresh it by calling the Token Exchange API again with your original key ID and secret key.

You can generate a new token before your previous token has expired. Generating a new token doesn't invalidate your previous token.

## Available roles

To view and manage the available roles for admin API authentication, go to [Unity Cloud](https://cloud.unity.com/), open the Account menu, select **Manage organization**, then in the Administration menu, select **Service Accounts**, and select a service account to see its assigned roles and permissions.