1. Experience Edge APIs

Token REST API

The Token REST API lets you programmatically create, list, rename, and revoke the Delivery GraphQL API tokens. The API tokens are long-lived and are not session-based tokens. After creating a token, you can continue to use it (with additional calls to the API) until you revoke it.

Note that you don't have to use the Token REST API to access the Delivery GraphQL API. Instead, you can use the credentials available in SitecoreAI Deploy.

The Token REST API cannot be used to manage tokens for the Preview GraphQL API.

Authorization and API access

For the base URL and authorization, see Authorization and API access options.

Endpoints

Create

Generates a Delivery GraphQL API token.

When you generate an API token, 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.

  • Route: https://edge.sitecorecloud.io/api/apikey/v1
  • HTTP verb: POST
  • Request body: Use the following JSON request body, replacing the placeholder with your Sitecore email address such as [email protected]:
json
{
  "CreatedBy": "<YOUR_SITECORE_USER_EMAIL>",
  "Label": "<DESCRIPTIVE_LABEL>",
  "Scopes": ["audience-delivery", "content-#everything#"]
}
  • Response: The response is the GraphQL Delivery API token. Review when and how to use the API token.
  • Example: The following example requests the scope of audience-delivery. This means that the returned sc_apikey is valid for the Delivery GraphQL API:
json
{
  "CreatedBy": "[email protected]",
  "Label": "Testing Access",
  "Scopes": [
    "audience-delivery",
    "content-#everything#"
  ]
}

ListAll

Lists information about all API tokens in your environment.

The tokens themselves are not returned, but information such as the environment ID, revoke status, label, scopes, creation date, the user that created the tokens, and the token hash are returned.

  • Route: https://edge.sitecorecloud.io/api/apikey/v1
  • HTTP verb: GET
  • Optional query string parameters:
    • scopes (array of strings) - Defines the scopes of the returned API tokens. If not provided, all API tokens are returned. The available scopes are audience-delivery and content-#everything#.
    • label (string) - Defines the label or part of the label to filter the API tokens. Information for all API tokens containing this string is returned. If not provided, information about all API tokens is returned.
    • pagesize (integer) - Defines the number of API tokens for which information is returned per page. Default: 20.
    • pagenumber (integer) - Defines the page number to be returned. Default: 1.
    • filterRevoked (boolean) - Defines whether the call returns information for all API tokens or for active, non-revoked tokens 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 as query string parameters.
json
{
  "totalCount": 2,
  "pageSize": 20,
  "currentPage": 1,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false,
  "keys": [
    {
      "TenantId": "<ENVIRONMENT_ID>",
      "Hash": "1b84...",
      "IsRevoked": false,
      "Label": "Example descriptive label",
      "Scopes": ["scope1", "scope2"],
      "CreatedBy": "[email protected]",
      "Created": "2020-12-02"
    },
    {
      "TenantId": "<ENVIRONMENT_ID>",
      "Hash": "example_hash_2",
      "IsRevoked": false,
      "Label": "Example descriptive label 2",
      "Scopes": ["scope3", "scope4"],
      "CreatedBy": "[email protected]",
      "Created": "2020-12-02"
    }
  ]
}

GetApiKeyByHash

Retrieves information about a single API token by its hash value.

  • Route: https://edge.sitecorecloud.io/api/apikey/v1/<HASH>
  • HTTP verb: GET
  • Route parameter:
    • hash (string) - The hash of the API token to retrieve information for.
  • Response: The response is the DeliveryApiKey that corresponds to the token:
json
{
  "TenantId": "<ENVIRONMENT_ID>",
  "Hash": "example_hash",
  "IsRevoked": false,
  "Label": "Example descriptive label",
  "Scopes": ["scope1", "scope2"],
  "CreatedBy": "[email protected]",
  "Created": "2020-12-02"
}

GetApiKeyByToken

Retrieves the details of a single API token identified by the token:

  • Route: https://edge.sitecorecloud.io/api/apikey/v1/token
  • HTTP verb: GET
  • Required header:
    • sc_apikey (string) - The Delivery GraphQL API token to retrieve information for.
  • Response: The response is the DeliveryApiKey that corresponds to the token:
json
[
  {
    "TenantId": "<ENVIRONMENT_ID>",
    "Hash": "example_hash",
    "IsRevoked": false,
    "Label": "Example descriptive label",
    "Scopes": ["scope1", "scope2"],
    "CreatedBy": "ADN",
    "Created": "2020-12-02"
  }
]

RenameByHash

Updates the label of an API token identified by the token's hash value:

  • Route: https://edge.sitecorecloud.io/api/apikey/v1/renamebyhash/<HASH>
  • HTTP verb: PUT
  • Route parameter:
    • hash (string) - The hash of the API token to rename.
  • Request body: The request body must contain the following field:
    • newName (string) - The new label for the API token.

Example:

json
{
  "newName": "new-label"
}
  • Response: 204 No Content indicates a successful request.

RenameByToken

Updates the label of an API token identified by the token itself.

  • Route: https://edge.sitecorecloud.io/api/apikey/v1/renamebytoken
  • HTTP verb: PUT
  • Required header:
    • sc_apikey (string) - The Delivery GraphQL API token to retrieve information for.
  • Request body: The request body must contain the following field:
    • newName (string) - The new label for the API token.

Example:

json
{
  "newName": "new-label"
}
  • Response: 204 No Content indicates a successful request.

RevokeByHash

Revokes an API token identified by its hash value:

  • Route: https://edge.sitecorecloud.io/api/apikey/v1/revokebyhash/<HASH>
  • HTTP verb: PUT
  • Route parameter:
    • hash (string) - The hash of the API token to revoke.
  • Response: 204 No Content indicates a successful request.

RevokeByToken

Revokes an API token identified by the token itself.

  • Route: https://edge.sitecorecloud.io/api/apikey/v1/revokebytoken
  • HTTP verb: PUT
  • Required header:
    • sc_apikey (string) - The Delivery GraphQL API token to retrieve information for.
  • Response: 204 No Content indicates a successful request.
If you have suggestions for improving this article, let us know!