NOnocodb
API Tokens

Create API token

Changed on

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.

post/api/v3/meta/tokens

Request

Request body

titlestring required

Title / description for the API token

expirystring 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_allowliststring[]

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.

Example request

{
  "title": "Github Integration",
  "scopes": [
    {
      "resource_type": "base",
      "resource_id": "p_abc123def456"
    }
  ],
  "expiry": "2026-12-30 15:17:24+00:00",
  "ip_allowlist": [
    "203.0.113.4",
    "10.0.0.0/8"
  ]
}

Response

Created API token. This is the only response that carries the token value.

idinteger required

Token ID

titlestring required

Token title / description

created_atstring date-time required

Token creation timestamp

updated_atstring date-time required

Token last update timestamp

token_prefixstring

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.

expirystring date-time nullable

Expiry timestamp, or null for a token that never expires. Always null outside Cloud and licensed self-hosted deployments.

enabledboolean

Whether the token is currently accepted. Fine-grained tokens only.

ip_allowliststring[]

IPv4/IPv6 addresses and CIDR ranges the token is accepted from, in canonical form. Absent when the token is unrestricted.

self_lockout_warningboolean

Present on create / update responses when the caller's own IP is outside the allowlist just set. The write still succeeds.

caller_ipstring

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_internalboolean

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_atstring 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.

tokenstring 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_.

Example response

{
  "id": 5,
  "title": "Github Integration",
  "created_at": "2025-12-30 15:17:24+00:00",
  "updated_at": "2025-12-30 15:17:24+00:00",
  "scopes": [
    {
      "resource_type": "base",
      "resource_id": "p_abc123def456"
    }
  ],
  "token_prefix": "nc_pat_wxAFz",
  "expiry": "2026-12-30 15:17:24+00:00",
  "enabled": true,
  "ip_allowlist": [
    "203.0.113.4",
    "10.0.0.0/8"
  ],
  "self_lockout_warning": true,
  "caller_ip": "203.0.113.4",
  "caller_ip_internal": true,
  "last_used_at": "2025-12-31 09:02:11+00:00",
  "token": "nc_pat_wxAFzFO2wwOf9ozVRjragBJ7KPWMaW2OGpklGqHh"
}

Changes

  • 62a735aaf849Revision changes
    • info

      added the new optional request property

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

  • 2ba4267a99d7Revision changes
    • breaking

      removed the success response with the status

    • warning

      the request property's maxLength was set to 255

    • info

      api operation id tokens-create was added

    • info

      the endpoint scheme security xc-token was removed from the API

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the success response with the status