Auth Tokens management

In order to read, append or import data into you Tinybird Analytics account, you’ll need an Auth Token with the right permissions. Tinybird Analytics uses Auth tokens to associate requests and permissions with your account.

Auth tokens overview

Auth tokens scopes can be applied to full datasources, or filtered rows.

You can find all your Auth tokens, create new ones, or delete existing ones using the following API or in the Console UI

Scopes and tokens

When an Auth token is created, you have the choice to give it a set of zero or more scopes that define which tables can be accessed by that token and which methods can be used to access them.

Available scopes syntax

Value

Description

DATASOURCES:CREATE

Enables your Auth token to create and append data to Datasources.

DATASOURCES:APPEND:datasource_name

Allows your Auth token to append data to the defined datasource.

DATASOURCES:DROP:datasource_name

Allows your Auth token to delete the specified datasource

DATASOURCES:READ:datasource_name

Gives your Auth token read permissions for the specified datasource

DATASOURCES:READ:datasource_name:sql_filter

Gives your Auth token read permissions for the specified table with the sql_filter applied

PIPES:CREATE

Allows your Auth token to create new pipes and manipulate existing ones.

PIPES:DROP:pipe_name

Allows your Auth token to delete the specified pipe

PIPES:READ:pipe_name

Gives your Auth token read permissions for the specified pipe

PIPES:READ:pipe_name:sql_filter

Gives your Auth token read permissions for the specified pipe with the sql_filter applied

TOKENS

Gives your Auth token the capacity of managing Auth tokens

ADMIN

All permissions will be granted, you should not use this token except in really specific cases. Use carefully!

Every method you can find in this page will require you to use an Auth token with TOKENS or ADMIN scope.

When adding the DATASOURCES:READ scope to a token it automatically gives read permissions to the “quarantine” datasource associated with it.

GET /v0/tokens/?
Get all tokens
curl -X GET "https://api.tinybird.co/v0/tokens"

Retrieve all user tokens.

Succesfull response
{
    "tokens": [
        {
            "name": "admin token",
            "scopes": [
                { "type": "ADMIN" }
            ],
            "token": "p.token"
        },
        {
            "name": "import token",
            "scopes": [
                { "type": "DATASOURCES:CREATE" }
            ],
            "token": "p.token0"
        },
        {
            "name": "token name 1",
            "scopes": [
                { "type": "DATASOURCES:READ", "resource": "table_name_1" },
                { "type": "DATASOURCES:APPEND", "resource": "table_name_1" }
            ],
            "token": "p.token1"
        },
        {
            "name": "token name 2",
            "scopes": [
                { "type": "PIPES:READ", "resource": "pipe_name_2" }
            ],
            "token": "p.token2"
        }
    ]
}
POST /v0/tokens/?
Creating a new token
curl -X POST "https://api.tinybird.co/v0/tokens/?name=test&scope=DATASOURCES:APPEND:table_name&scope=DATASOURCES:READ:table_name"

Creates a new Auth token.

Request parameters

Key

Type

Description

name

String

Name of the token

scope

String

Scope(s) to set. Format is SCOPE:TYPE[:arg][:filter]

Succesfull response
{
    "name": "token_name",
    "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’s 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

becomes

select count(1) from events_table where date > '2018-01-01' and type == 'foo'

Creating a new token with filter
curl -X POST "https://api.tinybird.co/v0/tokens/?name=test&scope=DATASOURCES:READ:table_name:column==1"
POST /v0/tokens/(.+)/refresh
Refreshing a token
curl -X POST "https://api.tinybird.co/v0/tokens/token/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.

Succesfull response
{
    "name": "token name",
    "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/(.+)
Getting token info
curl -X GET "https://api.tinybird.co/v0/tokens/token_name"

Fetch information about an Auth token. Returns a json with name and scopes.

Succesfull response
{
    "name": "token name",
    "scopes": [
        { "type": "DATASOURCES:READ", "resource": "table_name" }
    ],
    "token": "p.token"
}
DELETE /v0/tokens/(.+)
Deleting a token
curl -X DELETE "https://api.tinybird.co/v0/tokens/token_name"

Deletes an Auth token.

Succesfull response
{}
PUT /v0/tokens/(.+)
editing a token
curl -X PUT "https://api.tinybird.co/v0/tokens/token_name?name=test&scope=PIPES:READ:test_pipe&scope=DATASOURCES:CREATE"

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).

Request parameters

Key

Type

Description

name

String

Optional. Name of the token.

token

String

Auth token. Ensure it has the TOKENS scope on it

scope

String

Optional. Scope(s) to set. Format is SCOPE:TYPE[:arg][:filter]. New scope(s) will override existing ones.

Succesfull response
{
  "name": "test",
  "scopes": [
    { "type": "PIPES:READ", "resource": "test_pipe" },
    { "type": "DATASOURCES:CREATE" }
  ]
}