---
title: Static tokens
meta:
    description: Static tokens are permanent and long-term.
headingMaxLevels: 2
---
# Static tokens

Static tokens are permanent and long-term. They're stored inside Tinybird and don't have an expiration date or time. They will be valid until deleted or refreshed. They're useful for backend-to-backend integrations, where you call Tinybird as another service.

## Default tokens (created by Tinybird)

All workspaces come with a set of default tokens:

{% table %}
  * Token name {% width="30%" %}
  * Description
  ---
  * `Workspace admin token`
  * The Workspace token. This token is workspace-bound and enables any operation over it. Note: only workspace admins have access to this token.
  ---
  * `Admin <your-email> token`
  * The CLI token. This token is managed by Tinybird for you and the CLI uses it to authenticate via 'tb login' (stores it locally in the `.tinyb` file).
  ---
  * `User token`
  * Required only for certain operations through the API (like creating workspaces) - the system will ask you for it if required. 
{% /table %}

See below how to [list exiting tokens](#list-existing-tokens)

## User created tokens

Users can create additional tokens with different authorization scopes. This allow you to grant granular access to resources or to create tokens for CI/CD or for other purposes.

There are two types of static tokens:

- **[Resource-scoped tokens](#resource-scoped-tokens):** grant specific permissions on specific resources, such as reading from a given endpoint or appending to a given data source. Created in _.pipe_ and _.datasource_ files and managed via deployments.
- **[Workspace and Org. level tokens](#other-tokens):** tokens with workspace or organization-wide scopes: `WORKSPACE:READ_ALL`, `WORKSPACE:DEPLOY`, `ADMIN`, `TOKENS` or `ORG_DATASOURCES:READ`. Created and managed via the CLI or API.

### Resource-scoped tokens

When you create a resource-scoped token, you can define which resources can be accessed by that token, and which methods can be used to access them.

In datafile projects, resource-scoped tokens are managed using the `TOKEN` directive with the structure `TOKEN <token_name> <scope>`. In SDK projects, declare reusable token names and attach them to Data Sources, Pipes, or Endpoints with each resource's `tokens` option.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```tb {% title="events.datasource" %}
TOKEN events_append APPEND
TOKEN events_read READ

SCHEMA >
    `timestamp` DateTime `json:$.timestamp`,
    `payload` String `json:$.payload`

ENGINE "MergeTree"
ENGINE_SORTING_KEY "timestamp"
```

```tb {% title="events_api.pipe" %}
TOKEN events_read READ

NODE latest
SQL >
    SELECT timestamp, payload FROM events ORDER BY timestamp DESC LIMIT 100

TYPE ENDPOINT
```

{% /tab %}

{% tab label="TypeScript SDK" %}

```ts {% title="tinybird.ts" %}
import { defineDatasource, defineEndpoint, defineToken, engine, node, t } from "@tinybirdco/sdk";

export const eventsAppend = defineToken("events_append");
export const eventsRead = defineToken("events_read");

export const events = defineDatasource("events", {
  schema: {
    timestamp: t.dateTime(),
    payload: t.string(),
  },
  engine: engine.mergeTree({
    sortingKey: ["timestamp"],
  }),
  tokens: [
    { token: eventsAppend, scope: "APPEND" },
    { token: eventsRead, scope: "READ" },
  ],
});

export const eventsApi = defineEndpoint("events_api", {
  nodes: [
    node({
      name: "latest",
      sql: `SELECT timestamp, payload FROM events ORDER BY timestamp DESC LIMIT 100`,
    }),
  ],
  output: {
    timestamp: t.dateTime(),
    payload: t.string(),
  },
  tokens: [{ token: eventsRead, scope: "READ" }],
});
```

{% /tab %}

{% tab label="Python SDK" %}

```python {% title="tinybird.py" %}
from tinybird_sdk import define_datasource, define_endpoint, define_token, engine, node, t

events_append = define_token("events_append")
events_read = define_token("events_read")

events = define_datasource("events", {
    "schema": {
        "timestamp": t.date_time(),
        "payload": t.string(),
    },
    "engine": engine.merge_tree({"sorting_key": ["timestamp"]}),
    "tokens": [
        {"token": events_append, "scope": "APPEND"},
        {"token": events_read, "scope": "READ"},
    ],
})

events_api = define_endpoint("events_api", {
    "nodes": [
        node({
            "name": "latest",
            "sql": "SELECT timestamp, payload FROM events ORDER BY timestamp DESC LIMIT 100",
        }),
    ],
    "output": {
        "timestamp": t.date_time(),
        "payload": t.string(),
    },
    "tokens": [
        {"token": events_read, "scope": "READ"},
    ],
})
```

{% /tab %}
{% /tabs %}

{% callout type="info" %}
Resource-scoped tokens are created and updated through deployments. Tinybird will keep track of which ones to create or destroy based on all the tokens defined within the data files in your project. You can find the deployment-generated tokens in the Workspace UI or by running tb (--cloud) token ls.
{% /callout %}

The following scopes are available for resource-scoped tokens:

{% table %}
  * Token Scope (API) {% width="30%" %}
  * Token Scope (CLI) {% width="30%" %}
  * Description
  ---
  * `DATASOURCES:READ:datasource_name`
  * `TOKEN <token_name> READ` in `.datasource` files
  * Grants the token read permissions on the specified data source(s)
  ---
  * `DATASOURCES:APPEND:datasource_name`
  * `TOKEN <token_name> APPEND` in `.datasource` files
  * Grants the token permission to append data to the specified data source.
  ---
  * `PIPES:READ:pipe_name`
  * `TOKEN <token_name> APPEND` in `.pipe` files
  * Grants the token read permissions for the specified pipe.
{% /table %}

{% callout type="info" %}
When adding the `DATASOURCES:READ` scope to a token, it automatically grants read permissions to the [quarantine data source](/forward/guides/quarantine) associated with it.
{% /callout %}
{% callout type="caution" %}
SQL filters (`:sql_filter` suffix) are not supported in Tinybird Forward. Use fixed parameters in JWTs for row-level security instead.
{% /callout %}

### Other tokens

These are operational tokens that are not tied to specific resources. Run the following command in the CLI:

```bash
tb token create static new_admin_token --scope <scope> 
```

The following scopes are available for general tokens:

{% table %}
  * Value
  * Description
  ---
  * `TOKENS`
  * Grants the token permission to create, delete or refresh tokens.
  ---
  * `ADMIN`
  * Grants full access to the workspace. Use sparingly.
  ---
  * `WORKSPACE:READ_ALL`
  * Grants read access to all workspace resources: datasources, pipes, `tinybird.*` service data sources, and `system.*` tables. Particularly useful for BI Tools.
  ---
  * `WORKSPACE:DEPLOY`
  * Grants permission to run deploy-related operations in the workspace.
  ---
  * `ORG_DATASOURCES:READ`
  * Grants the token read access to organization service datasources.
{% /table %}

## List existing tokens

You can review your existing tokens using:

- **CLI**: Run `tb token ls` to list all tokens in your workspace. See [tb token](/forward/dev-reference/commands/tb-token) for reference.  
- **UI**: Navigate to the "Tokens" section in the sidebar of your Tinybird workspace.

## Refresh a static token

To refresh a token, run the `tb token refresh` command:

```bash
tb token refresh my_static_token
```

See [tb token](/forward/dev-reference/commands/tb-token) for more information.

## Delete a static token

### Resource-scoped tokens

Resource-scoped tokens are updated through deployments. Tinybird will keep track of which ones destroy based on all the tokens defined within the data files in your project. 

So, to remove a resource-scoped token, just **delete it from the data files and make a deployment.** The changes will be applied automatically.


### Other tokens

To delete [other tokens](/forward/core-concepts/static-tokens#other-tokens) that are not tied to specific resources, run the following command:

```bash
tb token rm <token_name>
```

See [tb token](/forward/dev-reference/commands/tb-token) for more information.

## Tinybird Local tokens

When working with [Tinybird Local](/forward/core-concepts/tinybird-local), you can authenticate by running `tb login`:

```bash
tb login
```

The command opens a browser window where you can sign in. See [tb login](/forward/dev-reference/commands/tb-login).

Credentials are stored in the `.tinyb` file. See [.tinyb file](/forward/dev-reference/datafiles/tinyb-file).

Tinybird Local also supports generating default user and workspace tokens for development and testing. This is especially useful in CI/CD pipelines, tests, or automated setups where dynamically [fetching tokens](/api-reference/token-api) adds unnecessary complexity.

### Generate Tinybird Local tokens

You can generate valid Tinybird Local tokens using the following [command](/forward/dev-reference/commands/tb-local):

```bash
tb local generate-tokens
```

This command outputs valid tokens for both a user token and a workspace token. You can then export them as environment variables:

```bash
TB_LOCAL_WORKSPACE_TOKEN=$(tb --output=json local generate-tokens | jq -r '.workspace_token')
TB_LOCAL_USER_TOKEN=$(tb --output=json local generate-tokens | jq -r '.user_token')
tb local start
```

Alternatively, you can pass the generated token values in the arguments to `tb local start`. The `generate-tokens` command prints the tokens to your console; you must copy these values to use in the start command:

```bash
tb local generate-tokens
tb local start --user-token=<USER_TOKEN> --workspace-token=<WORKSPACE_TOKEN>
```

Once Tinybird Local has started, you can reference `$TB_LOCAL_USER_TOKEN` and `$TB_LOCAL_WORKSPACE_TOKEN` as environment variables in your API calls or scripts from that shell session.