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

Static Tokens are permanent and long-term. Tinybird stores them without an expiration date or time. They remain valid until you delete or refresh them. 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 asks you for it if required.
{% /table %}

Learn how to [list existing 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" %}

```tinybird {% 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"
```

```tinybird {% 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" %}

```typescript {% 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" %}
Deployments create and update resource-scoped Tokens. Tinybird tracks which ones to create or destroy based on all the Tokens defined within the datafiles in your project. Find 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 sources
  ---
  * `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

Deployments update resource-scoped Tokens. Tinybird tracks which ones to destroy based on all the Tokens defined within the datafiles in your project.

To remove a resource-scoped Token, **delete it from the datafiles and deploy the project.** Tinybird applies the changes 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.