API Tokens

NocoDB supports two types of API tokens:

Fine-Grained API Tokens

Fine-grained API tokens give you precise control of what external integrations, scripts, and CI/CD pipelines can do in NocoDB. With fine-grained tokens, you can limit access to specific bases and to granular permission categories. Legacy tokens cannot do this.

Key Concepts

Create a Fine-Grained Token

1. Go to Account Settings > API Tokens.
2. Click Create New API Token. The create page opens. It has sections for name, expiration, access and scopes.

Each section starts with a default that works. Thus you can create a token without a change.

Name

Give your token a name that tells its purpose (for example, "CI/CD Pipeline", "Zapier Integration"). The name must have 1 to 255 characters.

The field starts with a generated name in the form user-yymmdd-hhmm. If you create the token from a base, the name starts with the base name.

Scopes (Permissions)

Set the operations that this token can do. The page lists all eight permission categories. Each category has its own access level:

New tokens start at Records: Read & write, Tables: Read and Fields: Read. All other categories start at None. To create the token, give access to a minimum of one category.

The eight permission categories are:

Access (Resource Scope)

Set the resources that this token can access. New tokens start with all resources selected. There are two options:

You can add multiple bases. The selected resources show in a list with a border. To remove an item, click its × button. If you add "All resources", NocoDB clears the single bases that you selected before.

Expiration

Select an expiration period from the dropdown:

On Community Edition and unlicensed self-hosted deployments, the expiration control is hidden, and tokens never expire.

To generate the token, click Create token.

Copy Your Token

After you create the token, the token string replaces the form. NocoDB shows the token string once. Copy it immediately and store it securely.

The token format is nc_pat_, then 40 random characters:

nc_pat_V1StGXR8_Z5jdHi2B-xoMwDqE3G4n5p6q7r8s

To copy the token, click the token field or the Copy token button. The button then changes to Back. Click Back to go back to the token list.

Create a Token From Within a Base

You can also create tokens from a base, and stay in the base.

1. Open the base.
2. Go to Base Settings → Create → API Tokens.

This page works the same way as Account Settings > API Tokens, with two differences:

• The token is pinned to the current base. Thus the page does not show the Access section.
• The generated name starts with the base name.

The list shows your tokens that are scoped to that base.

Manage Tokens

The token list shows all your API tokens in these columns:

A fine-grained token shows an Expired badge (red) after its expiry date. It shows an SSO badge (orange) if you created it through SSO authentication.

Token Actions

Edit a Token

When you click a row, the same form used for creation opens. It shows the current values of the token. You can update:

To apply the changes, click Save. To go back to the token list, click Cancel.

Enable / Disable a Token

To enable or disable a token, use the Active toggle on its row. A disabled token gets 401 Unauthorized on all requests. To restore access, enable the token again at any time. Disable a token to:

• examine suspicious activity, and not revoke access permanently
• stop an integration for a short time during maintenance

Permission Enforcement

For each API request, NocoDB does these checks:

1. Is the token valid? The token exists, is not expired, and is enabled.
2. Does the scope match? If the token is base-scoped, the requested base must be in the scope of the token. One exception: a base-scoped token can list the bases of a workspace. It gets back only the bases in its scope.
3. Does the user's role allow this operation? This is the standard role-based ACL check.
4. Does the token's permission level allow this operation? NocoDB maps the operation to a category and checks it against the level of the token.

All four checks must pass. The effective permission is the intersection of the user's role and the permissions given to the token.

Legacy API Tokens

Legacy tokens are org-scoped. They get the full role permissions of the creator. They continue to work for backward compatibility. For better security and control, we recommend that you change to fine-grained tokens.

If self-hosted administrators of a licensed instance need a transition period, they can set NC_ALLOW_LEGACY_API_TOKENS=true. This setting enables legacy token creation through the API again for a short time. Refer to Environment variables.

Create a Legacy Token (Deprecated)

1. In the bottom left corner of the sidebar, click User menu.
2. From the dropdown, select Account Settings.

3. On the Account Settings page, click the Tokens tab.
4. Click Add New API Token.
5. Enter the name of the API Token.
6. Click the Save button. NocoDB saves the changes.
7. To copy the API Token, click the Copy button in the Actions menu.

NocoDB adds the new API Token to the list. To copy the API token, click the Copy button in the Actions menu.

Delete a Token

1. In the bottom left corner of the sidebar, click User menu.
2. From the dropdown, select Account Settings.
3. On the Account Settings page, click the Tokens tab.
4. In the Actions menu of the API token that you want to delete, click the Delete button.

Authentication

Fine-grained tokens and legacy tokens both support two authentication methods:

Method 1: xc-token Header

curl -H "xc-token: nc_pat_..." https://your-nocodb.com/api/v3/...

Method 2: Authorization Header

curl -H "Authorization: Bearer nc_pat_..." https://your-nocodb.com/api/v3/...

The two methods are equivalent. Use the method that fits the authentication pattern of your application.

Security Best Practices

1. Set an expiration. Use the shortest expiry that you need. 90 days is a good default.
2. Use the least permissions necessary. A read-only dashboard needs only Records: Read.
3. Scope to specific bases. Do not use "All resources" when the integration needs access to only one base.
4. Rotate tokens regularly. Create a new token, update your integration, and then delete the old token.
5. Disable before deleting. If you think that a token is compromised, disable it immediately with the Active toggle. Examine the problem, then delete the token.
6. Store tokens securely. Use environment variables or a secrets manager. Never hardcode tokens in source code.
7. Audit your tokens. Review your token list regularly. Delete the tokens that you do not need.

API Token Access with SSO-Enabled Workspaces

If a workspace enforces Single Sign-On (SSO), only some tokens can access that workspace through the API. These are the tokens that you create after authenticating via SSO.

To access an SSO-enforced workspace through the API, users must:

1. Sign in using SSO.
2. Generate a new API token from their authenticated session.

Tokens that you create after SSO is enabled show a badge. The badge tells you that the token was generated through SSO authentication.

What Happens When SSO is Disabled?

If SSO is later disabled for a workspace:

• API tokens that were created through SSO authentication continue to work while the user is active and has the necessary permissions.
• Tokens that were created before SSO was enabled continue to work. They can now access the workspace without SSO authentication.
• NocoDB does not automatically revoke tokens when SSO is disabled.