# Token API

Use the XM Cloud Content Token API to manage query tokens for the GraphQL Query API. By setting an expiration date and applying restrictions, such as making the token valid only for a particular IP address or publish state, you can control how content is queried. <br> <br> The <b>Try it</b> functionality available from the API documentation lets you explore API endpoints and make calls directly from the documentation.
## Authentication
To use this API, you need:

 - The URL of your XM Cloud Content server.
 - A JWT bearer token requested using the [OAuth Client Credentials flow](https://doc.sitecore.com/xmc/en/developers/xm-cloud/request-a-jwt-for-experience-edge.html). This is sent with every request.

{% admonition type="info" name="Note" %}The token must include a scope. Which scope to use depends on the endpoint being called. For mutation operations, such as `create`, `update`, and `delete`, include the `cs:all:admin` scope. To read existing tokens, include the `cs.all:editor` scope. {% /admonition %}


Version: v2.0
License: closed source
Metadata:
  - product: SitecoreAI Content

## Servers

```
https://cs-tokenapi.sitecorecloud.io
```

## Security

### Bearer

A JSON Web Token (JWT) is sent with every call. To obtain one, you need an [bearer token and the client ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/generate-an-edge-token.html). You can create a token [using the Deploy REST API or by requesting one to the API itself](https://doc.sitecore.com/xmc/en/developers/xm-cloud/request-a-jwt-for-experience-edge.html).

Type: http
Scheme: Bearer
Bearer Format: JWT

## Download OpenAPI description

[Token API](https://api-docs.sitecore.com/_bundle/sai/token-api/index.yaml)

## Token

The Token API is responsible for generating and managing query tokens, which are used to authenticate access to the GraphQL Query API. These tokens can be configured to restrict access to specific branches, source IP addresses, and publishing states.


### Create a token

 - [POST /api/token/v2](https://api-docs.sitecore.com/sai/token-api/token/createtoken.md): Creates a query token. The scope and permissions of the token are specified through the request TokenParameters object that includes a required label and expiration date and time (such as "expiration": "2025-01-15T15:30:00Z"), an optional description, along with other restrictions, such as:

  - Publish State  - the publish state the token is restricted to (either Preview, Published, or both), for example, "publishState": ["Published"]. This property can be empty, but cannot be Unknown.
  - Branches - the name of the branches that token access is restricted to, for example, "branches": "main, dev, release/"]. For a prefix match, use /. This property can be empty.
  - Source IPs - the source IP addresses that token access is restricted to, for example, "sourceIPs": ["192.168.20.101"]. This property can be empty.
  - Origins - the origins that the token access is restricted to. This is a CORS feature and takes effect only when a request includes the Origin header. This property can be empty.
  - Introspection - whether GraphQL introspection is allowed when using this token. It is recommended that introspection only be enabled for development environments.

  {% admonition type="info" name="Note" %} We recommend an expiration date of one
  year at the most. You cannot change the expiration date after you create a token
  without generating a  new token.{% /admonition %}

### Retrieve a list of tokens

 - [GET /api/token/v2](https://api-docs.sitecore.com/sai/token-api/token/gettokens.md): Lists tokens for a specific tenant.

### Retrieve a token using its ID

 - [GET /api/token/v2/{id}](https://api-docs.sitecore.com/sai/token-api/token/gettokenbyid.md): Retrieves a specific token using its ID.

### Delete a specific token using its ID

 - [DELETE /api/token/v2/{id}](https://api-docs.sitecore.com/sai/token-api/token/deletetokenbyid.md): Deletes a specific token using its ID.

### Update a token using its ID

 - [PATCH /api/token/v2/{id}](https://api-docs.sitecore.com/sai/token-api/token/updatetokenbyid.md): Updates a specific token using its ID. When you update a token, you can omit properties that do not need to be updated. To remove a restriction, you can use null or an empty array.
{% admonition type="info" name="Note" %}Changing the expiration date generates a new query token.{% /admonition %}

### Rotate the signing key

 - [POST /api/token/v2/rotatekey](https://api-docs.sitecore.com/sai/token-api/token/rotatesigningkey.md): The signing key is used to digitally sign tokens and ensure their authenticity and integrity. Rotate the signing key to replace the current key with a new one that has updated security credentials.  This improves security and reduces the risk of compromised keys being used for malicious purposes: even if a previous key is exposed, future tokens remain secure. This enforces token expiration by making previously issued tokens invalid if they were signed with an old key. {% admonition type="info" name="Note" %}You cannot rotate the signing key if you already have one active key and two previous keys.{% /admonition %}