🚀Introducing Versions: Develop data products using Git.Join the waitlist

Tokens API

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

New to Auth Tokens? Read more about them here

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

GET /v0/tokens/?

Retrieves all workspace tokens.

Get all tokens
curl -X GET \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://api.tinybird.co/v0/tokens"

A list of your 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 Auth token.

Creating a new auth token
curl -X POST \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://api.tinybird.co/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]

Successful response
{
    "name": "token_name",
    "description": "",
    "scopes": [
        { "type": "DATASOURCES:APPEND", "resource": "table_name" }
        { "type": "DATASOURCES:READ", "resource": "table_name", "filter": "deparment = 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://api.tinybird.co/v0/tokens/" \
    -d "name=test&scope=DATASOURCES:READ:table_name:column==1"

Tokens with filters are specially useful when implementing multi-tenant applications with your data.

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

Refresh the Auth token without modifyng name, scopes or any other attribute. Specially useful when an Auth token is leaked, or when you need to rotate Auth tokens.

Refreshing a token
curl -X POST \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://api.tinybird.co/v0/tokens/token/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

Auth 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 Auth token.

Getting token info
curl -X GET \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://api.tinybird.co/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 an Auth token.

Deleting a token
curl -X DELETE \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://api.tinybird.co/v0/tokens/:token"
PUT /v0/tokens/(.+)

Modifies an Auth token. More than one scope can be sent per request, all of them will be added as Auth token scopes. Everytime an Auth token scope is modified, it overrides the existing one(s).

editing a token
curl -X PUT \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://api.tinybird.co/v0/tokens/<AUTH 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

Auth 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" }
  ]
}