Token API

Version: 22.x

The Token API is a REST API that enables you to 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 API base URL:

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

Authorization

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

  1. Create an Edge administration client for an environment. This generates a client ID and client secret.

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

The JSON web token (JWT) you requested to authorize your API requests.

Example:

Bearer eyJhbG...

Endpoints

The Token API has the following endpoints:

  • Create - generates an API key.

  • ListAll - lists all API keys in your tenant.

  • GetApiKeyByHash - retrieves a single API key by its hash value.

  • GetApiKeyByToken - retrieves a single API key identified by its token.

  • RenameByHash - renames an API key that was identified by its hash value.

  • RenameByToken - renames an API key that was identified by its token.

  • RevokeByHash - revokes an API key identified by its hash value.

  • RevokeByToken - revokes an API key identified by its token.

Create

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

  • audience-delivery - authorizes access to the Delivery API.

  • content-#everything# - allows access to all content.

You can not 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:

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

Response

The response is the token - a base 64 string. For example:

MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3

Example

The following example requests the scope of audience-delivery. This means that the returned sc_apikey is valid for the Delivery API:

RequestResponse
    {
        "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:

Name

Format

Purpose

scopes

Array of strings

Defines the scopes of the returned keys. If not provided, all keys are returned.

The available scopes are audience-delivery and content-#everything#.

label

String

Defines 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

Integer

Defines the number of keys returned per page. Default: 20.

pagenumber

Integer

Defines the page number to be returned. Default: 1 (returns the first page).

filterRevoked

Boolean

Defines 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

Note

The 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:

RequestResponse
{
  "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:

Name

Format

Purpose

hash

String

The hash of the key to retrieve.

Response

The response is the DeliveryApiKey that corresponds to the token:

RequestResponse
{
  "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:

Name

Format

Purpose

sc_apikey

String

The token of the key to retrieve.

Response

The response is the DeliveryApiKey that corresponds to the token:

RequestResponse
[
  {
    "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:

Name

Format

Purpose

hash

String

The hash of the key to rename.

Body

The body request must contain the following fields:

Name

Format

Purpose

newName

String

The 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:

Name

Format

Purpose

sc_apikey

String

The token of the key to be renamed.

Body

The body request must contain the following fields:

Name

Format

Purpose

newName

String

The 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:

Name

Format

Purpose

hash

String

The 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:

Name

Format

Purpose

sc_apikey

String

The token of the key to revoke.

Response

The response is a Boolean value indicating whether the key was revoked successfully.

Do you have some feedback for us?

If you have suggestions for improving this article,