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.

Environment variables are encrypted at rest.

Environment variables types¶

The Environment Variables API support different types of environment variables:

More types of environment variables types will be added soon.

API Limits¶

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.

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¶

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¶

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¶

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¶

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¶

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¶