NOnocodb
API Tokens

Update API token

Changed on

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.

patch/api/v3/meta/tokens/{tokenId}

Request

Path parameters

tokenIdstring required
Example:5

ID of the API token to update

Request body

titlestring

New title / description for the API token

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

enabledboolean

Whether the token is accepted. Disabling a token keeps it listed but stops it authenticating.

ip_allowliststring[] 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.

Example request

{
  "title": "Github Integration (read only)",
  "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

Updated API token, without 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.

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"
}

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
    • info

      endpoint added