--- title: "Update API token" method: PATCH path: "/api/v3/meta/tokens/{tokenId}" tags: ["API Tokens"] --- # Update API token `PATCH /api/v3/meta/tokens/{tokenId}` ## Request - Base URL: `https://app.nocodb.com` - URL: `https://app.nocodb.com/api/v3/meta/tokens/{tokenId}` - Auth: one of: - API key in header `xc-token` - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Update an API token's title, scopes, expiry or enabled flag. `expiry: null` clears the expiry. The token value is never returned. A caller who does not own the token gets `404`, unless they are a super admin. 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`. ## Path parameters - `tokenId` string, required ## Request body - object: Every field is optional; only the fields present are changed. - `title` string: New title / description for the API token - `scopes` ApiTokenScope[]: Replaces the token's scopes wholesale — the existing scope rows are deleted and these inserted. Omit to leave scopes untouched. - `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, nullable: New expiry; must be in the future. Send null to clear it. Honoured only on Cloud and licensed self-hosted deployments; elsewhere any value is treated as null. - `enabled` boolean: Whether the token is accepted. Disabling a token keeps it listed but stops it authenticating. - `ip_allowlist` string[], nullable: Replaces the allowlist. Send null or an empty array to remove the restriction; omit to leave it untouched. Setting or extending one needs Cloud or a licensed self-hosted deployment; without a license an existing allowlist can still be cleared or have entries removed. ## Response `200` Updated API token, without the token value - ApiTokenV3 - `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. ## 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. - `404`: The resource does not exist. Hooks and documents answer 404; most other resources answer 422 instead. - `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 `caller_ip` to the response with the `200` status - added the optional property `caller_ip_internal` to the response with the `200` status - added the optional property `ip_allowlist` to the response with the `200` status - …1 more - **2026-10-13** `2ba4267a99d7`: 1 info - endpoint added [Operation history](https://skmtc.dev/nocodb/apis/nocodb-v3/changes/api/v3/meta/tokens/:tokenId/patch.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)