Content Management API > API token

Update an API token

Updates an API token's name, role, or API surface flags. The token's secret value is not affected — to rotate it, use the Rotate API token endpoint.

If you omit relationships from the payload, the token's existing role is preserved. Send relationships.role only when you want to reassign the token to a different role.

Changes to the role or surface flags take effect immediately. A request that was permitted under the previous configuration may be rejected on the very next call once the new permissions have been written.

⚠️ Hardcoded tokens cannot be edited

The project's built-in factory tokens (those whose attributes.hardcoded_type is non-null) reject this endpoint with NON_EDITABLE_ACCESS_TOKEN. They can still be deleted or rotated.

Body parameters

type string Required

Must be exactly "access_token".

attributes.name string Required

Name of API token

Example:

"Read-only API token"

attributes.can_access_cda boolean Required

Whether this API token can call the Content Delivery API (graphql.datocms.com) to fetch published content.

attributes.can_access_cda_preview boolean Required

Whether this API token can call the Content Delivery API with the X-Include-Drafts: true header to fetch draft (current, unpublished) content. There is no separate endpoint — the CDA is a single GraphQL endpoint and this flag governs whether requesting drafts is allowed.

attributes.can_access_cma boolean Required

Whether this API token can access the Content Management API

relationships.role.data Optional

Role

Type: ResourceLinkage<"role">

Returns

Returns a resource object of type access_token.

Examples

1
PUT https://site-api.datocms.com/access_tokens/:access_token_id HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "access_token",
10
    "id": "312",
11
    "attributes": {
12
      "name": "Read-only API token",
13
      "can_access_cda": true,
14
      "can_access_cda_preview": true,
15
      "can_access_cma": true
16
    }
17
  }
18
}

1
curl -g 'https://site-api.datocms.com/access_tokens/:access_token_id' \
2
  -X PUT \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"access_token","id":"312","attributes":{"name":"Read-only API token","can_access_cda":true,"can_access_cda_preview":true,"can_access_cma":true}}}'

1
await fetch("https://site-api.datocms.com/access_tokens/:access_token_id", {
2
  method: "PUT",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: {
11
      type: "access_token",
12
      id: "312",
13
      attributes: {
14
        name: "Read-only API token",
15
        can_access_cda: true,
16
        can_access_cda_preview: true,
17
        can_access_cma: true,
18
      },
19
    },
20
  }),
21
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "access_token",
10
    "id": "312",
11
    "attributes": {
12
      "name": "Read-only API token",
13
      "hardcoded_type": "",
14
      "can_access_cda": true,
15
      "can_access_cda_preview": true,
16
      "can_access_cma": true,
17
      "last_cma_access": "never",
18
      "last_cda_access": "never"
19
    },
20
    "relationships": {
21
      "role": {
22
        "data": {
23
          "type": "role",
24
          "id": "34"
25
        }
26
      }
27
    }
28
  }
29
}

Update an API token

Body parameters

Returns

Examples

HTTP Request

CURL Request

fetch() Request

HTTP Response