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 as well.

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

You can list 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 Data Sources.
DATASOURCES:APPEND:datasource_name	Allows your Auth token to append data to the defined Data Sources.
DATASOURCES:DROP:datasource_name	Allows your Auth token to delete the specified Data Sources
DATASOURCES:READ:datasource_name	Gives your Auth token read permissions for the specified Data Sources
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 it 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/?

Retrieves all user 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",
            "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/?

Creates a new Auth token.

Creating a new auth token

curl -X POST \
    -H "Authorization: Bearer <ADMIN token>" \
    "https://api.tinybird.co/v0/tokens/?name=test&scope=DATASOURCES:APPEND:table_name&scope=DATASOURCES:READ:table_name"

Request parameters

Key	Type	Description
name	String	Name of the token
scope	String	Scope(s) to set. Format is SCOPE:TYPE[:arg][:filter]

Successful 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 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/?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",
    "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",
    "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/:token?name=test&scope=PIPES:READ:test_pipe&scope=DATASOURCES:CREATE"

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.

Successful response

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