Experience Edge APIs

Token API

Version:

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:

Create an Edge administration client for an environment. This generates a client ID and client secret.
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 REST 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 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:

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

{
        "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
scopesArray of stringsDefines the scopes of the returned keys. If not provided, all keys are returned.The available scopes are audience-delivery and content-#everything#.labelStringDefines 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.pagesizeIntegerDefines the number of keys returned per page. Default: 20.pagenumberIntegerDefines the page number to be returned. Default: 1 (returns the first page).filterRevokedBooleanDefines 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=3NoteThe 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
hashStringThe 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
sc_apikeyStringThe 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: NameFormatPurpose`hash`StringThe hash of the key to rename.
Body	The body request must contain the following fields: 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: NameFormatPurpose`sc_apikey`StringThe token of the key to be renamed.
Body	The body request must contain the following fields: 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: 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: NameFormatPurpose`sc_apikey`StringThe token of the key to revoke.
Response	The response is a Boolean value indicating whether the key was revoked successfully.

If you have suggestions for improving this article, let us know!