# 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](https://368680876-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqHXqMr0KYQT5OUP6gSt0%2Fuploads%2Fgit-blob-6a77af4a8b0a0cda01057defe60bd1f8a1e2e0cd%2Fapi-tokens-settings.png?alt=media)

{% 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](https://bluebricks.co/docs/api/reference/auth#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](https://bluebricks.co/docs/api/reference/auth#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](https://bluebricks.co/docs/api/reference/auth#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](https://bluebricks.co/docs/api/reference/auth#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