# Authentication ## Quick reference | Symptom | Cause | Fix | | --------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `bricks login` fails or times out | Browser did not open, code expired, or network blocking `auth.bluebricks.co` | Re-run `bricks login`; check network/proxy if it times out | | "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 | Generate a new key in **Account settings > Integrations > Bluebricks API Key** | | "User not authorized" | Session expired or credentials invalid | Re-authenticate with `bricks login` or verify API key | | "Not assigned to collection" | No access to the target collection | Request access from a collection owner | *** ## `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 expired**: the device code expires after a few minutes * **Network issues**: the CLI cannot reach `auth.bluebricks.co` (firewall, proxy, or VPN blocking outbound HTTPS) * **VPN or proxy interference**: corporate networks may block the polling requests between the CLI and 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 the CLI times out waiting for approval, check that your network allows outbound HTTPS to `auth.bluebricks.co`. For corporate networks with a proxy, set your terminal's `HTTPS_PROXY` environment variable. 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 > Bluebricks API Key** 2. Enter a name and generate a new 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 > Bluebricks API Key**. {% endtab %} {% endtabs %} *** ## "Login was denied" error The device authorization flow returns this error when the CLI cannot complete authentication. The error message begins with: `login was denied or cancelled. You may not have organization access, or you chose a personal account.` ### 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 * **No organization access**: your account is not a member of any Bluebricks organization ### 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/config.yaml` 4. **JWT token**: `~/.bricks/credentials.yaml` (set by `bricks login`) The first source found wins. The CLI also checks the current working directory for a `config.yaml`, which takes precedence over the home directory config. 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 > Bluebricks API Key** 2. Check that your key is listed and has not been revoked 3. If the key is missing or revoked, enter a name and 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 %} *** ## Not assigned to collection You see `User not assigned to collection` when you try to access a collection you do not have permissions for. This is different from "User not authorized," which means your session or credentials are invalid. Here, your authentication is fine, but you are not a member of the target collection. ### How to fix {% tabs %} {% tab title="Bluebricks app" %} 1. Ask a collection owner or organization admin to add you to the collection 2. The owner can do this from the collection's **Overview** tab under **Assigned users** 3. Once added, retry the operation {% endtab %} {% tab title="CLI" %} List the collections you have access to: ```bash bricks collection ls ``` If the target collection is not in the list, you need a collection owner or admin to grant you access. {% endtab %} {% endtabs %} {% hint style="info" %} For background on collection access control, see [Collections](https://docs.bluebricks.co/bluebricks-documentation/orchestration/collections) in the main documentation. {% endhint %} *** ## Need more help? 1. Enable logging: `bricks logger enable` 2. Reproduce the issue 3. Check `~/.bricks/logs/` for the latest log file (e.g., `bricks_14_04_2026.log`) 4. [Contact support](https://www.bluebricks.co/support) with the relevant log output --- # 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/help/troubleshooting/authentication.md?ask= ``` 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.