# 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:

{% tabs %}
{% tab title="macOS and Linux" %}

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

{% endtab %}

{% tab title="Windows PowerShell" %}

```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
```

{% endtab %}
{% endtabs %}

## 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](https://app.bluebricks.co/settings?tab=tokens)
* **API** - Use the Auth endpoints described below

### Prerequisites

Managing long-lived API tokens requires `Admin` role

### Token permissions

{% hint style="warning" %}
API tokens have a **fixed set of permissions** defined at the platform level. They do not inherit the creating user's role.
{% endhint %}

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](https://github.com/bluebricks-dev/Bluebricks-Documentation/blob/main/organization-management/roles-and-permissions.md).

### Create via UI

Navigate to [Settings > Tokens](https://app.bluebricks.co/settings?tab=tokens) in the Bluebricks app to create and manage your API tokens.

![API Tokens Settings](/files/QdNlS75MptTUaZVZpOeS)

{% hint style="warning" %}
**Important**: API tokens are only displayed once upon creation. Make sure to copy and store your token securely before closing the dialog.
{% endhint %}

### Create via API

Use the [POST Auth Key API](/docs/api/reference/auth.md#api-v1-auth-key) to create a long-lived API token:

```bash
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](#jwt-tokens) to authenticate the request.

{% hint style="warning" %}
**Important**: The API token is only returned once in the response. Make sure to copy and store it securely.
{% endhint %}

{% hint style="success" %}
Once you have a long-lived API token, it can authenticate requests to any endpoint within its permission scope.
{% endhint %}

### List via API

Use the [GET Auth Keys API](/docs/api/reference/auth.md#api-v1-auth-keys) 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](/docs/api/reference/auth.md#api-v1-auth-key-deactivate) 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](/docs/api/reference/auth.md#api-v1-auth-key-activate) 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:

```bash
# 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`:

```yaml
api_key: "bbx_your_api_key_here"
```

For full details on authentication methods and priority, see [CLI Authentication](https://docs.bluebricks.co/bluebricks-documentation/bricks-cli/authentication).

## CI/CD integration

### GitHub Actions

Use the [Bricks GitHub Action](https://docs.bluebricks.co/bluebricks-documentation/integrations/github-actions) to authenticate automated deployments:

```yaml
- 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

```bash
#!/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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/api/authenticate/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.