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 tokenThe 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> tokenThe 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 tokenRequired 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 ADMIN or TOKENS scope to interact with other Workspace resources, or with ORG_DATASOURCES:READ scope to query Organization level data sources. 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.

They are managed using the TOKEN directive in data files, with the following structure TOKEN <token_name> <scope>. Scopes are READ or APPEND.

For example in a .datasource file:

example.datasource
TOKEN app_read READ
TOKEN landing_read READ
TOKEN landing_append APPEND
SCHEMA >
    ...

For .pipe files, the behavior is the same:

example.pipe
TOKEN app_read READ

NODE node_1
SQL >
    %
    SELECT

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.

The following scopes are available for resource-scoped tokens:

Token Scope (API) Token Scope (CLI) Description
DATASOURCES:READ:datasource_nameTOKEN <token_name> READ in .datasource filesGrants the token read permissions on the specified data source(s)
DATASOURCES:APPEND:datasource_nameTOKEN <token_name> APPEND in .datasource filesGrants the token permission to append data to the specified data source.
PIPES:READ:pipe_nameTOKEN <token_name> APPEND in .pipe filesGrants 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:

ValueDescription
TOKENSGrants the token permission to create, delete or refresh tokens.
ADMINGrants full access to the workspace. Use sparingly.
ORG_DATASOURCES:READGrants the token read access to organization service datasources.

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 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. For example:

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.

Updated