API Authentication

Bluebricks API supports two authentication methods:

• Long-lived API Tokens - For automated workflows and CI/CD pipelines

• JWT Tokens - For personal authentication and testing

JWT Tokens

JWT tokens are obtained from the CLI or UI and are ideal for personal testing and development.

Extract JWT from CLI

After running bricks login, extract your JWT token:

macOS and Linux

token=$(awk '/^token:/ {sub(/token:[[:space:]]*/, ""); print; exit}' ~/.bricks/credentials.yaml)
curl -H "Authorization: ${token}" https://api.bluebricks.co/api/v1/environments

Windows PowerShell

$token = (Get-Content "$HOME\.bricks\credentials.yaml" | Select-String -Pattern '^token:' | ForEach-Object { $_ -replace '^token:\s*', '' })
curl -H "Authorization: $token" https://api.bluebricks.co/api/v1/environments

Long-lived API Tokens

Long-lived API tokens are essential for secure server-to-server communication, enabling seamless authentication without frequent renewals.

You can create and manage API tokens through:

• UI - Settings > Tokens

• API - Use the Auth endpoints described below

Prerequisites

Managing long-lived API tokens requires Admin role

Token permissions

API tokens have a fixed set of permissions defined at the platform level. They do not inherit the creating user's role.

API tokens cannot be used to:

• Invite or manage users

• Change organization settings

• Create, view, or manage API keys

These operations require JWT authentication (via bricks login or the UI).

For the full role and permission matrix, see Roles and Permissions.

Create via UI

Navigate to Settings > Tokens in the Bluebricks app to create and manage your API tokens.

API Tokens Settings

Important: API tokens are only displayed once upon creation. Make sure to copy and store your token securely before closing the dialog.

Create via API

Use the POST Auth Key API to create a long-lived API token:

curl https://api.bluebricks.co/api/v1/auth/key \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --data '{"name": "YOUR_TOKEN_NAME"}'

The name field is optional. If omitted, it defaults to "default".

For first-time creation, use your JWT token to authenticate the request.

Important: The API token is only returned once in the response. Make sure to copy and store it securely.

Once you have a long-lived API token, it can authenticate requests to any endpoint within its permission scope.

List via API

Use the GET Auth Keys API to list your long-lived API tokens:

curl https://api.bluebricks.co/api/v1/auth/keys \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Deactivate via API

Use the POST Auth Deactivate Key API to disable long-lived API tokens:

curl https://api.bluebricks.co/api/v1/auth/key/deactivate \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "YOUR_TOKEN_NAME_TO_DEACTIVATE"
}'

Activate via API

Use the POST Auth Activate Key API to enable long-lived API tokens:

curl https://api.bluebricks.co/api/v1/auth/key/activate \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "YOUR_TOKEN_NAME_TO_ACTIVATE"
}'

Using API tokens with Bricks CLI

Once you have a long-lived API token, you can use it with the Bricks CLI in three ways:

# Environment variable (recommended for CI/CD)
export BRICKS_API_KEY="bbx_your_api_key_here"

# CLI flag
bricks collection create --name "my_collection" --api-key "bbx_your_api_key_here"

You can also set the api_key field in ~/.bricks/environment.yaml:

api_key: "bbx_your_api_key_here"

For full details on authentication methods and priority, see CLI Authentication.

CI/CD integration

GitHub Actions

Use the Bricks GitHub Action to authenticate automated deployments:

- name: Deploy with Bricks
  uses: bluebricks-co/bricks-action@v1.0.0
  with:
    command: 'install'
    file: './deployments/main.yaml'
    api-key: ${{ secrets.BRICKS_API_KEY }}

Automation scripts

#!/bin/bash
export BRICKS_API_KEY="bbx_your_api_key_here"

# Automated deployment
bricks install --file ./deployments/prod.yaml --collection production

Security best practices

• Store securely: use environment variables or a secret management system; never hard-code tokens

• Rotate regularly: create a new key, update your workflows, then deactivate the old one

• Copy immediately: tokens are only displayed once upon creation

• Never commit to version control: add secrets to .gitignore and use CI/CD secret stores