--- title: "Create API token" method: POST path: "/api/v3/meta/tokens" tags: ["API Tokens"] --- # Create API token `POST /api/v3/meta/tokens` ## Request - Base URL: `https://app.nocodb.com` - URL: `https://app.nocodb.com/api/v3/meta/tokens` - Auth: one of: - API key in header `xc-token` - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a new API token for the organization. **Note**: This endpoint accepts a session credential only. An API token is rejected with 401 `ERR_API_TOKEN_NOT_ALLOWED`; an OAuth access token with 403 `ERR_FORBIDDEN`. **Note**: API Token APIs are available on all cloud-hosted plans, and on licensed self-hosted deployments (**Business** plan and above). > **Beta**: These APIs are currently in beta and subject to change in future releases. ## Request body - object - `title` string, required: Title / description for the API token - `scopes` ApiTokenScope[]: Access scopes for the token. Required on Cloud and on licensed self-hosted deployments — a request without at least one scope is rejected with `400`. For account-wide access send a single scope with `resource_type: all` and `resource_id: *`. - `id` string: Scope identifier. Returned on reads; ignored on writes. - `resource_type` 'base' | 'workspace' | 'all', required: What the scope names. `all` is account-wide: every resource the token's user can reach, present or future. - `resource_id` string, required: ID of the base or workspace the scope grants access to. Use `*` when `resource_type` is `all`. - `permissions` ApiTokenPermissions: Permission level per resource category. A category that is omitted is treated as `none`. An unknown category key is rejected with `400`. - `records` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `tables` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `fields` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `views` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `base` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `comments` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `webhooks` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `users` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `workflows` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `agents` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `scripts` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `integrations` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `environments` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `apps` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `workspaces` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `expiry` string, date-time: When the token stops working. Must be in the future. Honoured only on Cloud and licensed self-hosted deployments; elsewhere it is ignored and the token never expires. - `ip_allowlist` string[]: IPv4/IPv6 addresses and CIDR ranges the token may be used from, at most 50. Entries are stored in canonical form. Omit or send an empty array for no restriction. Honoured only on Cloud and licensed self-hosted deployments. ## Response `201` Created API token. This is the only response that carries the token value. - ApiTokenWithTokenV3 - `id` integer, required: Token ID - `title` string, required: Token title / description - `created_at` string, date-time, required: Token creation timestamp - `updated_at` string, date-time, required: Token last update timestamp - `scopes` ApiTokenScope[]: Access scopes attached to the token. Present on fine-grained tokens, which is every token minted through this API on Cloud and licensed self-hosted deployments. - `id` string: Scope identifier. Returned on reads; ignored on writes. - `resource_type` 'base' | 'workspace' | 'all', required: What the scope names. `all` is account-wide: every resource the token's user can reach, present or future. - `resource_id` string, required: ID of the base or workspace the scope grants access to. Use `*` when `resource_type` is `all`. - `permissions` ApiTokenPermissions: Permission level per resource category. A category that is omitted is treated as `none`. An unknown category key is rejected with `400`. - `records` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `tables` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `fields` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `views` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `base` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `comments` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `webhooks` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `users` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `workflows` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `agents` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `scripts` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `integrations` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `environments` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `apps` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `workspaces` 'none' | 'read' | 'write' | 'delete': Permission level for one resource category. `delete` is the top of the ladder and includes everything `write` allows. - `token_prefix` string: First 12 characters of the token value, kept for display. Fine-grained tokens only — the value itself is stored hashed and is never returned again after creation. - `expiry` string, date-time, nullable: Expiry timestamp, or null for a token that never expires. Always null outside Cloud and licensed self-hosted deployments. - `enabled` boolean: Whether the token is currently accepted. Fine-grained tokens only. - `ip_allowlist` string[]: IPv4/IPv6 addresses and CIDR ranges the token is accepted from, in canonical form. Absent when the token is unrestricted. - `self_lockout_warning` boolean: Present on create / update responses when the caller's own IP is outside the allowlist just set. The write still succeeds. - `caller_ip` string: The caller IP the server saw, returned with `self_lockout_warning`; IPv4-mapped IPv6 is given as plain IPv4. Behind a proxy it reflects `NC_TRUST_PROXY`: unset, it is the proxy's address. - `caller_ip_internal` boolean: Present when `caller_ip` is a private or loopback address, as it is for every caller behind a proxy when `NC_TRUST_PROXY` is unset. - `last_used_at` string, date-time: When the token was last used. Absent until the token has been used; updated on a 5-second batched flush, so it lags slightly behind live use. - `token` string, required: The actual API token value. Returned only on creation — it is stored hashed and cannot be retrieved again. Fine-grained tokens are prefixed `nc_pat_`. ## Other responses - `400`: The request body or a query parameter failed validation. - `401`: No credential was supplied, it was not valid, or this operation does not accept the kind of credential that was sent. - `403`: Authenticated, but not allowed: the role is too low, the token scope does not cover the operation, or the plan does not include the feature or allows no more of this resource. - `500`: Unexpected server error. The body carries `message` only — no `error` code. ## Changes - **2026-11-06** `62a735aaf849`: 5 info - added the new optional request property `ip_allowlist` - added the optional property `allOf[#/components/schemas/ApiTokenV3]/caller_ip` to the response with the `201` status - added the optional property `allOf[#/components/schemas/ApiTokenV3]/caller_ip_internal` to the response with the `201` status - added the optional property `allOf[#/components/schemas/ApiTokenV3]/ip_allowlist` to the response with the `201` status - …1 more - **2026-10-13** `2ba4267a99d7`: 1 breaking, 1 warning, 9 info - removed the success response with the status `200` - the `title` request property's maxLength was set to `255` - api operation id `tokens-create` was added - the endpoint scheme security `xc-token` was removed from the API - …7 more [Operation history](https://skmtc.dev/nocodb/apis/nocodb-v3/changes/api/v3/meta/tokens/post.md) --- [API](https://skmtc.dev/nocodb/apis/nocodb-v3.md) - [All operations](https://skmtc.dev/nocodb/apis/nocodb-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/nocodb/apis/nocodb-v3/revisions/62a735aaf849?raw)