--- title: "List API tokens" method: GET path: "/api/v3/meta/tokens" tags: ["API Tokens"] --- # List API tokens `GET /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) Retrieve a list of all API tokens 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. ## Query parameters - `limit` integer - `offset` integer - `baseId` string ## Response `200` List of API tokens - object - `list` 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. - `pageInfo` object: Offset-based page information. This endpoint uses the v1 paging envelope rather than the cursor paging used elsewhere in v3. When `baseId` is supplied the result is unpaginated and only `totalRows` is present. - `totalRows` integer: Total number of API tokens the caller can see, counted with the same filters as the list — their own tokens, or every token for a super admin. - `page` integer: Current page number, derived from `offset` and `limit` - `pageSize` integer: Effective page size after the per-deployment cap is applied - `isFirstPage` boolean - `isLastPage` boolean ## Other responses - `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`: 4 info - added the optional property `list/items/caller_ip` to the response with the `200` status - added the optional property `list/items/caller_ip_internal` to the response with the `200` status - added the optional property `list/items/ip_allowlist` to the response with the `200` status - added the optional property `list/items/self_lockout_warning` to the response with the `200` status - **2026-10-13** `2ba4267a99d7`: 14 info - api operation id `tokens-list` was added - the endpoint scheme security `xc-token` was removed from the API - added the new optional `query` request parameter `baseId` - added the new optional `query` request parameter `limit` - …10 more [Operation history](https://skmtc.dev/nocodb/apis/nocodb-v3/changes/api/v3/meta/tokens/get.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)