Token API¶
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://api.tinybird.co/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://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]. 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 isevents_table
andfilter
isdate > '2018-01-01' and type == 'foo'
a query likeselect count(1) from events_table
will becomeselect 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"
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://api.tinybird.co/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://api.tinybird.co/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 itResponse 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
orTOKENS
scope
- GET /v0/tokens/(.+)¶
Fetches information about a particular Static 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 a Static Token .
Deleting a token¶curl -X DELETE \ -H "Authorization: Bearer <ADMIN token>" \ "https://api.tinybird.co/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://api.tinybird.co/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 itname
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" } ] }