Secrets API

The Secrets API allows you to create, update, delete, and list secrets that can be used in Pipes in a Workspace. Secrets allow you to store sensitive information, such as access secrets in your Workspace.

Using the Secrets API requires a Workspace admin token.

Secrets are encrypted at rest.

API Limits

Check the limits page for limits on ingestion, queries, API Endpoints, and more.

The Secrets API has limits of:

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

Templating

Once you've created secrets 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')}})

Secrets 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 secrets with the same name in both Workspaces, changing only their corresponding value.

Branch use

Secrets can be used in Branches, but they must be created in the main Workspace initially. Secrets have the same value in the main Workspace as in the Branches. You cannot create a secret in a Branch to be deployed in the main Workspace.

POST /v0/secrets/?

Creates a new secret.

Restrictions

Secret names are unique for a Workspace.

Example

curl \
  -X POST "https://$TB_HOST/v0/secrets" \
  -H "Authorization: Bearer <ADMIN token>" \
  -d "name=test_secret" \
  -d "value=test"

Request parameters

KeyTypeDescription
nameStringThe name of the secret
valueStringThe secret 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/secrets/(.+)

Deletes a secret.

Example

curl \
  -X DELETE "https://$TB_HOST/v0/secrets/test_secret" \
  -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 secret not found

PUT /v0/secrets/(.+)

Updates a secret.

Example

curl \
  -X PUT "https://$TB_HOST/v0/secrets/test_secret" \
  -H "Authorization: Bearer <ADMIN token>" \
  -d "value=new_value"

Successful response example

{
    "name": "test_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 secret not found

GET /v0/secrets/?

Retrieves all Workspace secrets. The value is not returned.

Example

curl \
  -X GET "https://$TB_HOST/v0/secrets" \
  -H "Authorization: Bearer <ADMIN token>"

Successful response example

{
    "secrets": [
        {
            "name": "test_token",
            "created_at": "2024-06-21T10:27:57",
            "updated_at": "2024-06-21T10:27:57",
            "edited_by": "token: 'admin token'"
        },
        {
            "name": "test_token2",
            "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/secrets/(.+)

Fetches information about a particular secret. The value is not returned.

Example

curl \
  -X GET "https://$TB_HOST/v0/secrets/test_secret" \
  -H "Authorization: Bearer <ADMIN token>"

Successful response example

{
    "name": "test_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 secret not found