# Authentication

## Quick reference

| Symptom                           | Cause                                | Fix                                                              |
| --------------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
| `bricks login` fails or times out | Browser did not complete device flow | Re-run `bricks login` and enter the code in the browser          |
| "Login was denied" error          | Signed in with a personal account    | Re-run `bricks login` and use an organization account            |
| "Token expired" errors            | JWT token has expired                | Run `bricks logout` then `bricks login`                          |
| Wrong credentials being used      | Multiple auth sources configured     | Check the [priority order](#authentication-priority-order) below |
| API key rejected                  | Key revoked or invalid               | Regenerate in **Account Settings > Integrations > API Keys**     |
| "User not authorized"             | Insufficient permissions             | Contact your organization admin                                  |

***

## `bricks login` fails or times out

Bricks CLI uses a device authorization flow. When you run `bricks login`, the CLI displays a verification code and opens your browser to complete authentication.

### Common causes

* **Browser did not open**: your terminal cannot launch a browser (common in headless or SSH sessions)
* **Code not entered in time**: the device code expires after a few minutes
* **Network issues**: the CLI cannot reach the authentication server

### How to fix

{% tabs %}
{% tab title="CLI" %}

1. Run `bricks login` again
2. If the browser does not open, manually navigate to the URL shown in the terminal
3. Enter the device code displayed in your terminal
4. After the browser confirms success, return to the terminal

```bash
bricks login
```

If you are in a headless environment (CI/CD, SSH), use an [API key](https://docs.bluebricks.co/bluebricks-documentation/bricks-cli/authentication/authenticate-using-long-lived-tokens) instead of interactive login.
{% endtab %}

{% tab title="Bluebricks app" %}
API keys can be created in the Bluebricks app without using the CLI login flow:

1. Go to **Account Settings > Integrations > API Keys**
2. Click **Create API Key**
3. Copy the key and set it as an environment variable:

```bash
export BRICKS_API_KEY=bbx_your_key_here
```

{% endtab %}
{% endtabs %}

***

## Token expired errors

JWT tokens issued by `bricks login` expire after a set period. When a token expires, CLI commands return authentication errors.

### How to fix

{% tabs %}
{% tab title="CLI" %}

```bash
bricks logout
bricks login
```

Verify the new session:

```bash
bricks whoami
```

{% endtab %}

{% tab title="Bluebricks app" %}
If you use API keys for automation, tokens do not expire unless revoked. Check that your key is still active in **Account Settings > Integrations > API Keys**.
{% endtab %}
{% endtabs %}

***

## "Login was denied" error

The device authorization flow returns this error when the CLI cannot complete authentication. This typically means you signed in with a personal account or cancelled the authorization in the browser.

### Common causes

* **Personal account selected**: Bluebricks requires an organization account. Personal accounts are not supported.
* **Authorization cancelled**: you closed the browser tab or clicked "Deny" during the approval step

### How to fix

Run `bricks login` again and sign in with your organization account when prompted in the browser.

```bash
bricks login
```

If you are unsure which account to use, check with your organization admin.

***

## Authentication priority order

When multiple authentication sources are configured, the CLI resolves them in this order:

1. **CLI flag**: `--api-key` passed directly to the command
2. **Environment variable**: `BRICKS_API_KEY`
3. **Config file**: `~/.bricks/environment.yaml`
4. **JWT token**: `~/.bricks/credentials.yaml` (set by `bricks login`)

The first source found wins. If you are getting unexpected behavior, check whether a higher-priority source is overriding your intended credentials.

{% hint style="warning" %}
Do not store real API keys in shared CI/CD logs or version control. Use environment variables or secret managers to inject `BRICKS_API_KEY` at runtime.
{% endhint %}

***

## API key rejected

API keys can be rejected if they have been revoked, are malformed, or belong to a different organization.

### How to fix

{% tabs %}
{% tab title="Bluebricks app" %}

1. Go to **Account Settings > Integrations > API Keys**
2. Check that your key is listed and has not been revoked
3. If the key is missing or revoked, click **Create API Key** to generate a new one
4. Update your environment variable or config with the new key
   {% endtab %}

{% tab title="CLI" %}
Test your current authentication:

```bash
bricks whoami
```

If the command fails, set a valid key and retry:

```bash
export BRICKS_API_KEY=bbx_your_new_key_here
bricks whoami
```

{% endtab %}
{% endtabs %}

***

## Still stuck?

1. Enable logging: `bricks logger enable`
2. Reproduce the issue
3. Check `~/.bricks/bricks-cli.log` for detailed error messages
4. [Contact support](https://www.bluebricks.co/support) with the relevant log output