# Create a new API token

Creates a new API token for the project. Each token combines a **Role** (which actions are permitted) with a set of **API surface flags** (`can_access_cda`, `can_access_cda_preview`, `can_access_cma`) that gate which APIs the token can call at all. Effective capabilities are the *intersection* of the two layers.

> [!POSITIVE] ✅ A CDA-only token + write-capable role is safe by construction
> The Content Delivery API has no write endpoints. If a token has `can_access_cda: true` (and/or `can_access_cda_preview: true`) but `can_access_cma: false`, attaching it to a role with `update`/`publish`/`delete` permissions is harmless — those actions have no surface to act on. This is useful when you want to share a single Role definition between an editor (who acts via the dashboard / CMA) and the public-facing read token of the same project (used by a frontend / CDA).

The new token's secret is returned in `attributes.token` of the response (and on every subsequent read, as long as the caller has `can_manage_access_tokens`).

## Body parameters

**`name`**

- Required
- Type: string
- Example: `"Read-only API token"`

Name of API token

**`can_access_cda`**

- Required
- Type: boolean

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

**`can_access_cda_preview`**

- Required
- Type: boolean

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.

**`can_access_cma`**

- Required
- Type: boolean

Whether this API token can access the Content Management API

**`role`**

- Required
- Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md)

Role

## Returns

Returns a resource object of type [access\_token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)

## Other examples

###### Example CDA-only token bound to a write-capable role

An API token bound to a **write-capable role**, but with the Content Management API surface *closed off*: only `can_access_cda` is enabled. Any attempt to use this token against `site-api.datocms.com` returns 401, while the same token can freely query `graphql.datocms.com` for published content.

The role on its own would let a credential edit, publish, and delete records. The CDA has no write endpoints, so attaching it here is harmless: the role's write permissions have no surface to act on. This is the safety-by-construction story called out on the [API token resource overview](https://www.datocms.com/docs/content-management-api/resources/access-token.md).

Code

```javascript
import { buildClient } from "@datocms/cma-client-node";

async function run() {
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  // Look up the write-capable role this token will be bound to.
  const allRoles = await client.roles.list();
  const role = allRoles.find(
    (candidate) => candidate.name === "Editorial team",
  )!;

  // Create a token with the full role attached, but with the CMA closed off.
  // Result: this token can only fetch published content via the CDA — its
  // role's update/publish/delete capabilities have no surface to act on.
  const accessToken = await client.accessTokens.create({
    name: "Public CDA token",
    role: { type: "role", id: role.id },
    can_access_cda: true,
    can_access_cda_preview: false,
    can_access_cma: false,
  });

  console.log("Created token:", accessToken.id, "—", accessToken.name);
  console.log("Secret value:", accessToken.token);
  console.log("Effective surfaces: CDA only (CMA disabled)");
}

run();
```

Returned output

```javascript
Created token: 407203 — Public CDA token
Secret value: 427db8a23d5777bbb5bb363d405380
Effective surfaces: CDA only (CMA disabled)
```

## Related content in "Content Management API"

- [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md)
- [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md)
- [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md)
- [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md)
- [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md)
- [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)
- [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md)
- [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md)
- [CMA Technical Limits & Rate Limits](https://www.datocms.com/docs/content-management-api/technical-limits.md)
- [Record](https://www.datocms.com/docs/content-management-api/resources/item.md)
- [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md)
- [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md)
- [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)
- [Site](https://www.datocms.com/docs/content-management-api/resources/site.md)
- [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md)
- [Field](https://www.datocms.com/docs/content-management-api/resources/field.md)
- [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)
- [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md)
- [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md)
- [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md)
- [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md)
- [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md)
- [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md)
- [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md)
- [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md)
- [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md)
- [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md)
- [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md)
- [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md)
- [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md)
- [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md)
- [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md)
- [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md)
- [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md)
- [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md)
- [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md)
- [Account](https://www.datocms.com/docs/content-management-api/resources/account.md)
- [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md)
- [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md)
- [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md)
- [Role](https://www.datocms.com/docs/content-management-api/resources/role.md)
- [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)
- [Create a new API token](https://www.datocms.com/docs/content-management-api/resources/access-token/create.md)
- [Update an API token](https://www.datocms.com/docs/content-management-api/resources/access-token/update.md)
- [List all API tokens](https://www.datocms.com/docs/content-management-api/resources/access-token/instances.md)
- [Retrieve an API token](https://www.datocms.com/docs/content-management-api/resources/access-token/self.md)
- [Rotate API token](https://www.datocms.com/docs/content-management-api/resources/access-token/regenerate_token.md)
- [Delete an API token](https://www.datocms.com/docs/content-management-api/resources/access-token/destroy.md)
- [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md)
- [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md)
- [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md)
- [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md)
- [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md)
- [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md)
- [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md)
- [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md)
- [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md)
- [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md)
- [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)