Authentication

Resolve login failures, expired tokens, API key issues, and collection access errors with the Bricks CLI and Bluebricks app

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

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

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 instead of interactive login.

Bluebricks app

---

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

CLI

bricks logout
bricks login

Verify the new session:

bricks whoami

Bluebricks app

---

"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.

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.

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.

---

API key rejected

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

How to fix

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

CLI

---

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

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

CLI

For background on collection access control, see Collections in the main documentation.

---

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 with the relevant log output