Environment Variables API¶

Use the Environment Variables API to create, update, delete, and list environment variables that you can use in Pipes in a Workspace.

Environment variables allow you to store sensitive information, such as access secrets and host names, in your Workspace. Environment variables are encrypted at rest.

Environment variables types¶

The Environment Variables API supports different types of environment variables:

Limits¶

The Environment Variables API has the following limits:

• 5 requests per second.
• 100 environment variables per Workspace.
• 8 KB max size of the value attribute.

Templating¶

After creating 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.

Branch use¶

You can use environment variables in Branches, but you must create them in the main Workspace initially. Environment variables have the same value in the main Workspace as in the Branches. You can't 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 isn't 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 isn't 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¶