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 typeComments
secretUsed 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 ClickHouse® 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

KeyTypeDescription
typeString (optional)The type of the variable. Defaults to secret
nameStringThe name of the variable
valueStringThe 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

CodeDescription
200OK
400Invalid or missing parameters
403Limit reached or invalid token
404Workspace 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

CodeDescription
200OK
400Invalid or missing parameters
403Limit reached or token invalid
404Workspace 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

CodeDescription
200OK
400Invalid or missing parameters
403Limit reached or token invalid
404Workspace 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

CodeDescription
200OK
400Invalid or missing parameters
403Limit reached or token invalid
404Workspace 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

CodeDescription
200OK
400Invalid or missing parameters
403Limit reached or token invalid
404Workspace or variable not found
Tinybird is not affiliated with, associated with, or sponsored by ClickHouse, Inc. ClickHouse® is a registered trademark of ClickHouse, Inc.
Updated