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 you have created a key, you can continue to use it (with additional calls to the API) until you revoke it.

When you generate a key, you must define the scope. 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.

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

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.

The Token API has the following endpoints:

Create

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": ["scope1", "scope2"]
}

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 keys that are to be returned. If not provided, all keys are returned.

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 to be returned.

pagesize

Integer

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

pagenumber

Integer

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

Use the following example structure to query using parameters:

https://edge.sitecorecloud.io/api/apikey/v1?scopes=audience-delivery&scopes=content-someid&label=mine&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 that was 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 that was 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.