Environment Variables API¶
The Environment Variables API allows you to create, update, delete, and list environment variables that can be used in Pipes in a Workspace. Environment variables allow you to store sensitive information, such as access secrets and hostnames, in your Workspace.
Using the Environment Variables API requires a Workspace admin token.
Environment variables are encrypted at rest.
Environment variables types¶
The Environment Variables API support different types of environment variables:
Environment variable type | Comments |
---|---|
secret | Used to store passwords and other secrets, automatically prevents Endpoint from exposing its value. It's the default type. |
More types of environment variables types will be added soon.
API Limits¶
Check the limits page for limits on ingestion, queries, API Endpoints, and more.
The Environment Variables API has limits of:
- 5 requests per second.
- 100 environment variables per Workspace.
- 8KB max size of the
value
attribute.
Templating¶
Once you've created environment variables in a Workspace, you can use the tb_secret
template function to replace the original value:
% SELECT * FROM postgresql('host:post', 'database', 'table', 'user', {{tb_secret('pg_password')}})
Environment variables values are rendered as String
data type. If you need to use a different type, use any of the functions to cast a String value to a given type. For example:
% SELECT * FROM table WHERE int_value = toUInt8({{tb_secret('int_secret')}})
Staging and production use¶
If you have staging and production Workspaces, create the same environment variables with the same name in both Workspaces, changing only their corresponding value.
Tinybird doesn't allow you to create an API Endpoint when exposing environment variables with type=secret
in a SELECT clause. So, while it's possible to have a Node that uses the logic SELECT {{tb_secret('username')}}
, you can't publish that Node as a Copy Pipe or API Endpoint.
Branch use¶
Environment variables can be used in Branches, but they must be created in the main Workspace initially. Environment variables have the same value in the main Workspace as in the Branches. You cannot create a environment variable in a Branch to be deployed in the main Workspace.
POST /v0/variables/?¶
Creates a new environment variable.
Restrictions¶
Environment variables names are unique for a Workspace.
Example¶
curl \ -X POST "https://$TB_HOST/v0/variables" \ -H "Authorization: Bearer <ADMIN token>" \ -d "type=secret" \ -d "name=test_password" \ -d "value=test"
Request parameters¶
Key | Type | Description |
---|---|---|
type | String (optional) | The type of the variable. Defaults to secret |
name | String | The name of the variable |
value | String | The variable value |
Successful response example¶
{ "name": "test_token", "created_at": "2024-06-21T10:27:57", "updated_at": "2024-06-21T10:27:57", "edited_by": "token: 'admin token'" }
Response codes¶
Code | Description |
---|---|
200 | OK |
400 | Invalid or missing parameters |
403 | Limit reached or invalid token |
404 | Workspace not found |
DELETE /v0/variables/(.+)¶
Deletes a environment variable.
Example¶
curl \ -X DELETE "https://$TB_HOST/v0/variables/test_password" \ -H "Authorization: Bearer <ADMIN token>"
Successful response example¶
{ "ok": true }
Response codes¶
Code | Description |
---|---|
200 | OK |
400 | Invalid or missing parameters |
403 | Limit reached or token invalid |
404 | Workspace or variable not found |
PUT /v0/variables/(.+)¶
Updates a environment variable.
Example¶
curl \ -X PUT "https://$TB_HOST/v0/variables/test_password" \ -H "Authorization: Bearer <ADMIN token>" \ -d "value=new_value"
Successful response example¶
{ "name": "test_password", "type": "secret", "created_at": "2024-06-21T10:27:57", "updated_at": "2024-06-21T10:29:57", "edited_by": "token: 'admin token'" }
Response codes¶
Code | Description |
---|---|
200 | OK |
400 | Invalid or missing parameters |
403 | Limit reached or token invalid |
404 | Workspace or variable not found |
GET /v0/variables/?¶
Retrieves all Workspace environment variables. The value is not returned.
Example¶
curl \ -X GET "https://$TB_HOST/v0/variables" \ -H "Authorization: Bearer <ADMIN token>"
Successful response example¶
{ "variables": [ { "name": "test_token", "type": "secret", "created_at": "2024-06-21T10:27:57", "updated_at": "2024-06-21T10:27:57", "edited_by": "token: 'admin token'" }, { "name": "test_token2", "type": "secret", "created_at": "2024-06-21T10:27:57", "updated_at": "2024-06-21T10:29:57", "edited_by": "token: 'admin token'" } ] }
Response codes¶
Code | Description |
---|---|
200 | OK |
400 | Invalid or missing parameters |
403 | Limit reached or token invalid |
404 | Workspace not found |
GET /v0/variables/(.+)¶
Fetches information about a particular environment variable. The value is not returned.
Example¶
curl \ -X GET "https://$TB_HOST/v0/variables/test_password" \ -H "Authorization: Bearer <ADMIN token>"
Successful response example¶
{ "name": "test_password", "type": "secret", "created_at": "2024-06-21T10:27:57", "updated_at": "2024-06-21T10:27:57", "edited_by": "token: 'admin token'" }
Response codes¶
Code | Description |
---|---|
200 | OK |
400 | Invalid or missing parameters |
403 | Limit reached or token invalid |
404 | Workspace or variable not found |