# API Tokens

> Part of the NocoDB documentation (Product docs > Account & Billing). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL.

URL: https://nocodb.com/docs/product/account-settings/api-tokens
Last updated: 2026-10-03

Create and manage NocoDB API tokens, including fine-grained tokens with scoped permissions.

NocoDB supports two types of API tokens:

| Type                    | Description                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| **Fine-grained tokens** | Scoped to specific bases with granular permission categories. Use them for all new integrations. |
| **Legacy tokens**       | Org-wide tokens. They get the full role permissions of the creator.                              |

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

<Callout type="info">
  Granular scope and permission controls (base selection, permission categories, token expiration) are available on all 

  **NocoDB Cloud**

   plans and licensed self-hosted deployments (Business plan and above). On Community Edition and unlicensed self-hosted deployments, tokens default to all-resources access and never expire.
</Callout>

### Key Concepts

| Concept                | Description                                                                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Intersection model** | A token can only *restrict* what your role already allows. It never gives more permissions than your role.                                                             |
| **Deny by default**    | The token gets only the permission categories that you add. All other categories are denied.                                                                           |
| **Show-once token**    | NocoDB shows the token string only when you create the token. You cannot get it again later. NocoDB stores the token as a SHA-256 hash and never stores the plaintext. |

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

<img alt="The Create New API Token page" src={__img0} placeholder="blur" />

#### 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:

| Access level     | Description                                  |
| ---------------- | -------------------------------------------- |
| **Read**         | Read-level access for that category          |
| **Read & write** | Full read and write access for that category |
| **None**         | No access for that category                  |

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.

<img alt="The eight scope categories and their access levels" src={__img1} placeholder="blur" />

The eight permission categories are:

| Category                                           | Read                     | Read & write                 |
| -------------------------------------------------- | ------------------------ | ---------------------------- |
| **Records**: record CRUD, data export, aggregation | List, read, export       | Create, update, delete       |
| **Comments**: record comments                      | View comments            | Post, edit, delete           |
| **Tables**: table management                       | List, read               | Create, update, delete       |
| **Fields**: column/field management                | List columns             | Create, update, delete       |
| **Views**: views, sorts, filters, sharing          | List views and config    | Create, update, delete       |
| **Webhooks**: webhook triggers and logs            | List, view logs          | Create, update, delete, test |
| **Base**: base settings, sources, jobs             | View info, swagger, jobs | Create sources, delete base  |
| **Users**: base and workspace members              | List members             | Invite, update roles, remove |

#### Access (Resource Scope)

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

| Option                | Description                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Add all resources** | The token can access all current and future bases in all workspaces.                                         |
| **Add a base**        | Opens a searchable dropdown with the bases grouped by workspace. Select single bases to give access to them. |

<img alt="Add a base dropdown" src={__img2} placeholder="blur" />

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.

<img alt="All resources selected" src={__img3} placeholder="blur" />

<Callout type="info">
  At least one resource must be selected on all 

  **NocoDB Cloud**

   plans and licensed self-hosted deployments (Business plan and above). Use 

  **Add all resources**

   for org-wide access, or 

  **Add a base**

   to restrict to specific bases. On Community Edition and unlicensed self-hosted deployments, tokens automatically have all-resources access.
</Callout>

#### Expiration

Select an expiration period from the dropdown:

| Option                                                                  | Description             |
| ----------------------------------------------------------------------- | ----------------------- |
| **7 days**, **30 days**, **60 days**, **90 days**, **1 year** (default) | Preset options          |
| **Custom**                                                              | Select a specific date  |
| **No expiration**                                                       | The token never expires |

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

<Callout type="info">
  We recommend setting an expiration for better security. Expired tokens are automatically rejected.
</Callout>

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.

<img alt="The token shown once after creation" src={__img4} placeholder="blur" />

<Callout type="warn">
  This token will not be displayed again after you leave this screen. If you lose it, you must delete the token and create a new one.
</Callout>

### 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**](#access-resource-scope) section.
* The generated name starts with the base name.

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

<img alt="The API Tokens page in base settings" src={__img5} placeholder="blur" />

<img alt="Creating a token from a base, with no Access section and a base-prefixed name" src={__img6} placeholder="blur" />

### Manage Tokens

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

| Column         | What it shows                                                              |
| -------------- | -------------------------------------------------------------------------- |
| **Token Name** | The name of the token.                                                     |
| **Created**    | A relative time, for example "14m ago".                                    |
| **Expires**    | The days that remain, for example "365 days left".                         |
| **Active**     | A toggle.                                                                  |
| **Actions**    | The token actions.                                                         |
| **Creator**    | Only super admins see this column. Their list has the tokens of all users. |

<img alt="The API token list" src={__img7} placeholder="blur" />

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

| Action                  | How to do it                                                                    |
| ----------------------- | ------------------------------------------------------------------------------- |
| **Edit**                | Click anywhere on the token row. The edit form opens in place of the list view. |
| **Delete** (trash icon) | Click the trash icon. Confirm the deletion in the row.                          |

#### Edit a Token

When you click a row, the [same form used for creation](#create-a-fine-grained-token) opens. It shows the current values of the token. You can update:

| Setting                                               | Change                                                                                 |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Token name**                                        | Change the name.                                                                       |
| [**Scopes (Permissions)**](#scopes-permissions)       | Add, remove, or change permission categories and their access levels.                  |
| [**Access (Resource Scope)**](#access-resource-scope) | Add or remove bases, or change to all resources.                                       |
| [**Expiration**](#expiration)                         | Extend the expiry date or set a new one. The **Keep** option keeps the current expiry. |

<img alt="Expiration dropdown in edit mode" src={__img8} placeholder="blur" />

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.

| Scenario                                      | HTTP Status |
| --------------------------------------------- | ----------- |
| Token is valid and has sufficient permissions | `200`       |
| Token is expired                              | `401`       |
| Token is disabled                             | `401`       |
| Token does not exist or is malformed          | `401`       |
| Token scope does not match the requested base | `401`       |
| Token permission level is insufficient        | `403`       |

## Legacy API Tokens

<Callout type="warn">
  Legacy token creation is no longer available in the UI. As of v2026.08.1, creating legacy tokens through the API is also blocked on 

  **NocoDB Cloud**

   and licensed self-hosted deployments. On Community Edition and unlicensed self-hosted deployments, the V1 API still supports creating them for backward compatibility. Existing legacy tokens continue to work everywhere. Use fine-grained tokens for all new integrations.
</Callout>

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](/docs/self-hosting/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`.

<img alt="profile page" src={__img9} placeholder="blur" />

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.

<img alt="Create API Token" src={__img10} placeholder="blur" />

<img alt="Create API Token" src={__img11} placeholder="blur" />

<Callout type="info">
  Legacy API tokens do not expire, but can be deleted anytime.
</Callout>

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

<img alt="Create API Token" src={__img12} placeholder="blur" />

### Delete a Token

<Callout type="warn">
  All services using the API token will stop working once the token is deleted.
</Callout>

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.

<img alt="Delete API Token" src={__img13} placeholder="blur" />

## Authentication

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

### Method 1: xc-token Header

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

### Method 2: Authorization Header

```bash
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**.

<Callout type="warn">
  **Tokens created before SSO was enabled**

   do not have the necessary identity context and 

  **will not work**

   for SSO-enforced workspaces.
</Callout>

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.

<Callout type="info">
  Tokens created before SSO enforcement may still work for other workspaces that do not require SSO.
</Callout>

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

<img alt="API Token SSO Badge" src={__img14} placeholder="blur" />

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

---

## Related pages

- [Profile Page](https://nocodb.com/docs/product/account-settings/profile-page.md): Manage your profile name and delete your account on the NocoDB profile page.
- [Language Settings](https://nocodb.com/docs/product/account-settings/language.md): Change the language of the NocoDB user interface.
- [Appearance](https://nocodb.com/docs/product/account-settings/appearance.md): Customize the appearance of the NocoDB interface and switch between the Light, Dark and System modes.
- [Experimental Features](https://nocodb.com/docs/product/account-settings/experimental-features.md): Enable or disable experimental features in NocoDB to try new capabilities before they are generally available.
- [In Community Edition](https://nocodb.com/docs/product/account-settings/oss-specific-details.md): Account settings that are specific to NocoDB Community Edition.