Token API¶

The API host in the following examples must match your Workspace's region. See the full list of regions and hosts

The Token API allows you to list, create, update or delete your Tinybird Static Tokens.

New to Static Tokens? Read more about them in the Tokens docs.

The :sql_filter suffix on resource-scoped tokens (e.g. DATASOURCES:READ:datasource_name:sql_filter and PIPES:READ:pipe_name:sql_filter) is not supported in Tinybird Forward and will result in an error.

All endpoints require authentication using a Token with TOKENS or ADMIN scope.

GET /v0/tokens/?¶

Retrieves all workspace Static Tokens.

Get all tokens¶

curl -X GET \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens"

A list of your Static Tokens and their scopes will be sent in the response.

Successful response¶

{
    "tokens": [
        {
            "name": "admin token",
            "description": "",
            "scopes": [
                { "type": "ADMIN" }
            ],
            "token": "p.token"
        },
        {
            "name": "import token",
            "description": "",
            "scopes": [
                { "type": "DATASOURCES:CREATE" }
            ],
            "token": "p.token0"
        },
        {
            "name": "token name 1",
            "description": "",
            "scopes": [
                { "type": "DATASOURCES:READ", "resource": "table_name_1" },
                { "type": "DATASOURCES:APPEND", "resource": "table_name_1" }
            ],
            "token": "p.token1"
        },
        {
            "name": "token name 2",
            "description": "",
            "scopes": [
                { "type": "PIPES:READ", "resource": "pipe_name_2" }
            ],
            "token": "p.token2"
        }
    ]
}

POST /v0/tokens/?¶

Creates a new Token: Static or JWT

Creating a new Static Token¶

curl -X POST \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens/" \
    -d "name=test&scope=DATASOURCES:APPEND:table_name&scope=DATASOURCES:READ:table_name"

Request parameters¶
Key	Type	Description
name	String	Name of the token
description	String	Optional. Markdown text with a description of the token.
scope	String	Scope(s) to set. Format is SCOPE:TYPE[:arg][:filter]. This is only used for the Static Tokens

Successful response¶

{
    "name": "token_name",
    "description": "",
    "scopes": [
        { "type": "DATASOURCES:APPEND", "resource": "table_name" }
        { "type": "DATASOURCES:READ", "resource": "table_name", "filter": "department = 1"},
    ],
    "token": "p.token"
}

When creating a token with filter whenever you use the token to read the table, it will be filtered. For example, if table is events_table and filter is date > '2018-01-01' and type == 'foo' a query like select count(1) from events_table will become select count(1) from events_table where date > '2018-01-01' and type == 'foo'

Creating a new token with filter¶

curl -X POST \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens/" \
    -d "name=test&scope=DATASOURCES:READ:table_name:column==1"

If we provide an expiration_time in the URL, the token will be created as a JWT Token.

Creating a new JWT Token¶

curl -X POST \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens?name=jwt_token&expiration_time=1710000000" \
    -d '{"scopes": [{"type": "PIPES:READ", "resource": "requests_per_day", "fixed_params": {"user_id": 3}}]}'

In multi-tenant applications, you can use this endpoint to create a JWT token for a specific tenant where each user has their own token with a fixed set of scopes and parameters

POST /v0/tokens/(.+)/refresh¶

Refresh the Static Token without modifying name, scopes or any other attribute. Specially useful when a Token is leaked, or when you need to rotate a Token.

Refreshing a Static Token¶

curl -X POST \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens/:token_name/refresh"

When successfully refreshing a token, new information will be sent in the response

Successful response¶

{
    "name": "token name",
    "description": "",
    "scopes": [
        { "type": "DATASOURCES:READ", "resource": "table_name" }
    ],
    "token": "NEW_TOKEN"
}

Request parameters¶
Key	Type	Description
auth_token	String	Token. Ensure it has the `TOKENS` scope on it

Response codes¶
Code	Description
200	No error
403	Forbidden. Provided token doesn’t have permissions to drop the token. A token is not allowed to remove itself, it needs `ADMIN` or `TOKENS` scope

GET /v0/tokens/(.+)¶

Fetches information about a particular Static Token.

Getting token info¶

curl -X GET \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens/:token"

Returns a json with name and scopes.

Successful response¶

{
    "name": "token name",
    "description": "",
    "scopes": [
        { "type": "DATASOURCES:READ", "resource": "table_name" }
    ],
    "token": "p.TOKEN"
}

DELETE /v0/tokens/(.+)¶

Deletes a Static Token .

Deleting a token¶

curl -X DELETE \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens/:token"

PUT /v0/tokens/(.+)¶

Modifies a Static Token. More than one scope can be sent per request, all of them will be added as Token scopes. Every time a Token scope is modified, it overrides the existing one(s).

editing a token¶

curl -X PUT \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://<your_host>/v0/tokens/<Token>?" \
    -d "name=test_new_name&description=this is a test token&scope=PIPES:READ:test_pipe&scope=DATASOURCES:CREATE"

Request parameters¶
Key	Type	Description
token	String	Token. Ensure it has the `TOKENS` scope on it
name	String	Optional. Name of the token.
description	String	Optional. Markdown text with a description of the token.
scope	String	Optional. Scope(s) to set. Format is SCOPE:TYPE[:arg][:filter]. New scope(s) will override existing ones.

Successful response¶

{
  "name": "test",
  "description": "this is a test token",
  "scopes": [
    { "type": "PIPES:READ", "resource": "test_pipe" },
    { "type": "DATASOURCES:CREATE" }
  ]
}