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.
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 of API token
"Read-only API token"
Whether this API token can call the Content Delivery API (graphql.datocms.com) to fetch published content.
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.
Whether this API token can access the Content Management API
Returns
Returns a resource object of type access_token
Other examples
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.
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();Created token: 407203 — Public CDA tokenSecret value: 427db8a23d5777bbb5bb363d405380Effective surfaces: CDA only (CMA disabled)