Experience Edge APIs

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:

Create an Edge administration client for an environment. This generates a client ID and client secret.
Create a JSON web token (JWT) 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

Authorization: required. Use the JSON web token (JWT) you requested to authorize your API requests. Format: Bearer <YOUR_JWT> 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:

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:

text

MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3

Example: the following example requests the audience-delivery scope. 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:
- 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:

text

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:

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:
- hash (String): the 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:
- sc_apikey (String): the 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:
- hash (String): the hash of the key to rename.
Body:
- 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:
- sc_apikey (String): the token of the key to be renamed.
Body:
- 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:
- 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:
- sc_apikey (String): the 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!