Token API

Abstract

Describes the Token API for Experience Edge for XM.

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

The base URL for Token API requests is: https://edge.sitecorecloud.io/api/apikey/v1

Authentication

All endpoints use bearer authorization.

Headers

The following header is required:

Name	Format	Purpose
`Authorization`	`Bearer {Token}`	A JSON web token (JWT). Request a JWT for Experience Edge XM using OAuth.

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

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

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

[
  {
    "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.