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:
| Token name | 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. |
See below how to list exiting 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: 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: tokens with workspace or organization-wide scopes:
WORKSPACE:READ_ALL,WORKSPACE:DEPLOY,ADMIN,TOKENSorORG_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.
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"
events_api.pipe
TOKEN events_read READ
NODE latest
SQL >
SELECT timestamp, payload FROM events ORDER BY timestamp DESC LIMIT 100
TYPE ENDPOINT
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.
The following scopes are available for resource-scoped tokens:
| Token Scope (API) | Token Scope (CLI) | 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. |
When adding the DATASOURCES:READ scope to a token, it automatically grants read permissions to the quarantine data source associated with it.
SQL filters (:sql_filter suffix) are not supported in Tinybird Forward. Use fixed parameters in JWTs for row-level security instead.
Other tokens¶
These are operational tokens that are not tied to specific resources. Run the following command in the CLI:
tb token create static new_admin_token --scope <scope>
The following scopes are available for general tokens:
| 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. |
List existing tokens¶
You can review your existing tokens using:
- CLI: Run
tb token lsto list all tokens in your workspace. See 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:
tb token refresh my_static_token
See 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 that are not tied to specific resources, run the following command:
tb token rm <token_name>
See tb token for more information.
Tinybird Local tokens¶
When working with Tinybird Local, you can authenticate by running tb login:
tb login
The command opens a browser window where you can sign in. See tb login.
Credentials are stored in the .tinyb file. See .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 adds unnecessary complexity.
Generate Tinybird Local tokens¶
You can generate valid Tinybird Local tokens using the following command:
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:
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:
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.