---
title: "Token API"
slug: "token-api"
abstract: "Describes the Token API for Experience Edge."
---
# Token API

The Token REST API lets you manage the API keys used to access the Delivery API. These API keys are long-lived and are not session-based tokens. After creating a key, you can continue to use it (with additional calls to the API) until you revoke it.

## Base URL

Here's the Token REST API base URL:

`https://edge.sitecorecloud.io/api/apikey/v1`

## Authorization

All endpoints use bearer authorization. To authorize your API requests:

1. Get your client ID and client secret from Sitecore.
2. [Request a JWT for Experience Edge XM using OAuth](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/request-a-jwt-for-experience-edge-xm-using-oauth.html "Request a JWT for Experience Edge XM using OAuth") using the client ID and client secret. This generates a JSON web token (JWT). You must include the JWT in the `Authorization` header of every API request you make.

### Headers

| Name | Format | Description |
| --- | --- | --- |
| `Authorization` | `Bearer <YOUR_JWT>` | Required.<br><br>The JSON web token (JWT) you requested to authorize your API requests.<br><br>Example:<br><br>`Bearer eyJhbG...` |

## Endpoints

The Token REST API has the following endpoints:

- [`Create`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_section-idm4665300977347232404261682929 "Create") - generates an API key.
- [`ListAll`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_section-idm4628058716102432404280271967 "ListAll") - lists all API keys in your tenant.
- [`GetApiKeyByHash`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_N1623050619141 "GetApiKeyByHash") - retrieves a single API key by its hash value.
- [`GetApiKeyByToken`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_N1623050651040 "GetApiKeyByToken") - retrieves a single API key identified by its token.
- [`RenameByHash`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_N1623050663984 "RenameByHash") - renames an API key that was identified by its hash value.
- [`RenameByToken`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_N1623050633344 "RenameByToken") - renames an API key that was identified by its token.
- [`RevokeByHash`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_N1623050604515 "RevokeByHash") - revokes an API key identified by its hash value.
- [`RevokeByToken`](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/token-api.html#UUID-c877b7de-b82c-6e07-c27d-298bc838d689_N1623050582454 "RevokeByToken") - revokes an API key identified by its token.

### Create

When you generate an API key, you must define audience and content scopes. The following scopes are required for Experience Edge:

- `audience-delivery` - authorizes access to the Delivery GraphQL API.
- `content-#everything#` - allows access to all content.

You cannot create additional scopes or scope types.

The `Create` endpoint generates an API key:

- Relative route: `/`
- HTTP verb: `POST`
- Body: The structure of DeliveryApiKeyInfo is as follows:

```json
{
  "CreatedBy": "userName",
  "Label": "Example key",
  "Scopes": ["audience-delivery", "content-#everything#"]
}

```

- Response: The response is the API token, which is a base 64 string. Example API token:`MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3`
- Example: The following example requests the scope of audience-delivery. This means that the returned sc_apikey is valid for the Delivery GraphQL API:

```json
{
        "CreatedBy": "sitecore\sueb",
        "Label": "Testing Access",
        "Scopes": [
            "content-#everything#",
            "audience-delivery"
        ]
    }

```

### ListAll

The `ListAll` endpoint lists all API keys in your tenant:

- Relative route: `/`
- HTTP verb: `GET`
- Query string parameters: The following parameters are required:NameFormatPurpose`scopes`Array of stringsDefines the scopes of the returned keys. If not provided, all keys are returned.The available scopes are `audience-delivery` and `content-#everything#`.`label`StringDefines the label or part of the label to filter the keys. All keys containing this string are returned. If not provided, all keys are returned.`pagesize`IntegerDefines the number of keys returned per page. Default: 20.`pagenumber`IntegerDefines the page number to be returned. Default: 1 (returns the first page).`filterRevoked`BooleanDefines whether the call returns all keys or active keys only.Use the following example structure to query using parameters:`https://edge.sitecorecloud.io/api/apikey/v1?scopes=audience-delivery&label=mine&filterRevoked=true&pagesize=50&pagenumber=3`NoteThe `scopes` parameter is enumerable. It can appear multiple times in the query string.
- Response: The response is an array of DeliveryApiKey that satisfies the filters and paging settings provided along with the paging metadata:

```json
{
  "totalCount": 2,
  "pageSize": 20,
  "currentPage": 1,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false,
  "keys": [
    {
      "TenantId": "Sitecore-tenant-id",
      "Hash": "1b84ed5b25f0eaa3a301fe72e89dc266362b999522a131d2de47744d7001cd07",
      "IsRevoked": false,
      "Label": "Example key",
      "Scopes": ["scope1", "scope2"],
      "CreatedBy": "ADN",
      "Created": "2020-12-02"
    },
    {
      "TenantId": "Sitecore-tenant-id",
      "Hash": "example_hash_2",
      "IsRevoked": false,
      "Label": "Example key 2",
      "Scopes": ["scope3", "scope4"],
      "CreatedBy": "ADN",
      "Created": "2020-12-02"
    }
  ]
}

```

### GetApiKeyByHash

The `GetApiKeyByHash` endpoint retrieves a single API key by its hash value:

- Relative route: `/{hash}`
- HTTP verb: `GET`
- Route parameters: The following parameter is required:NameFormatPurpose`hash`StringThe hash of the key to retrieve.
- Response: The response is the DeliveryApiKey that corresponds to the token:

```json
{
  "TenantId": "Sitecore-tenant-id",
  "Hash": "example_hash",
  "IsRevoked": false,
  "Label": "Example key",
  "Scopes": ["scope1", "scope2"],
  "CreatedBy": "ADN",
  "Created": "2020-12-02"
}

```

### GetApiKeyByToken

The `GetApiKeyByToken` endpoint retrieves a single API key identified by its token:

- Relative route: `/token`
- HTTP verb: `GET`
- Header: The following header is required:NameFormatPurpose`sc_apikey`StringThe token of the key to retrieve.
- Response: The response is the DeliveryApiKey that corresponds to the token:

```json

  {
    "TenantId": "Sitecore-tenant-id",
    "Hash": "example_token",
    "IsRevoked": false,
    "Label": "Example key",
    "Scopes": ["scope1", "scope2"],
    "CreatedBy": "ADN",
    "Created": "2020-12-02"
  }
]

```

### RenameByHash

The `RenameByHash` endpoint renames an API key identified by its hash value:

| Relative route | `/renamebyhash/{hash}` |
| --- | --- |
| HTTP verb | `PUT` |
| Route parameters | The following parameter is required:<br><br>NameFormatPurpose`hash`StringThe hash of the key to rename. |
| Body | The body request must contain the following fields:<br><br>NameFormatPurpose`newName`StringThe new name of the API key. |
| Response format | The response is a Boolean value indicating whether the key was renamed successfully. |

### RenameByToken

The `RenameByToken` endpoint renames an API key identified by its token:

| Relative route | `/renamebytoken` |
| --- | --- |
| HTTP verb | `PUT` |
| Header | The following header is required:<br><br>NameFormatPurpose`sc_apikey`StringThe token of the key to be renamed. |
| Body | The body request must contain the following fields:<br><br>NameFormatPurpose`newName`StringThe new name of the API key. |
| Response | The response is a Boolean value indicating whether the key was renamed successfully. |

### RevokeByHash

The `RevokeByHash` endpoint revokes an API key identified by its hash value:

| Relative route | `/revokebyhash/{hash}` |
| --- | --- |
| HTTP verb | `PUT` |
| Route parameters | The following parameter is required:<br><br>NameFormatPurpose`hash`StringThe hash of the key to revoke. |
| Response | The response is a Boolean value indicating whether the key was revoked successfully. |

### RevokeByToken

The `RevokeByToken` endpoint revokes an API key identified by its token.

| Relative route | `/revokebytoken` |
| --- | --- |
| HTTP verb | `PUT` |
| Header | The following header is required:<br><br>NameFormatPurpose`sc_apikey`StringThe token of the key to revoke. |
| Response | The response is a Boolean value indicating whether the key was revoked successfully. |