Skip to main content
Version: v12

API Token Authentication

API tokens let you authenticate with Brinqa Platform APIs — such as the BQL API and the BrinqaIQ MCP integration — without exchanging a username and password on every request.

API tokens are tied to a specific user account and inherit that user's access control permissions (ACL/RBAC). This means a token can only access data that the associated user is authorized to see.

Generate an API token​

To generate an API token, follow these steps in the Brinqa Platform UI:

  1. Click the account icon (person circle) at the bottom of the left sidebar.
  2. Select API Tokens from the dropdown menu.
  3. On the API Tokens page, click the + (create) button in the header.
  4. In the Generate API Token dialog, fill in:
    • Token name (required): A descriptive name to identify this token's purpose (e.g., SOAR Vulnerability Export). Max 255 characters. Letters, numbers, spaces, hyphens, underscores, and periods are allowed.
    • Expiration: Select one of: 1 Month, 3 Months, 6 Months, 12 Months, or Never expires.
  5. Click Generate. The raw token (starting with brq_) is displayed once.
warning

Copy and store the token securely immediately. It is not shown again. If lost, you must revoke the token and generate a new one.

The API Tokens page also lets you view all your tokens with their status, creation date, expiration date, and last used date.

Token creation restrictions​

  • Non-administrator users can only create a new token if they have no active tokens, or if their current active token is within 30 days of expiration.
  • System administrators can create tokens at any time.

Use your API token​

Include the API token in the Authorization header using the ApiKey scheme:

Authorization: ApiKey brq_AbCdEfGh.xYz123...

For example, to call the BQL API with curl:

curl -X POST 'https://<your-brinqa-instance>/v1/api/bql' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey brq_AbCdEfGh.xYz123...' \
  -d '{
    "query": "FIND Vulnerability",
    "returningFields": ["id", "name"],
    "limit": 10
  }'

Token format​

A raw API token has the form brq_<id>.<secret>:

  • brq_ is a fixed prefix that identifies the value as a Brinqa API token. The prefix is intentional: it lets secret-scanning tools recognize a leaked token.
  • <id> identifies the token record.
  • <secret> is the secret portion. Treat the whole token as a credential. Never commit it to source control or share it.

The platform rejects a malformed token with 401 Unauthorized before it looks the token up. A token is malformed when it is missing the brq_ prefix, uses a different prefix, has no . separator between the id and the secret, or carries an oversized secret. A well-formed token that is unknown, revoked, or expired is also rejected with 401.

Token lifecycle​

StatusDescription
ActiveThe token can be used for authentication.
InactiveThe token has been manually revoked and cannot be used. It can be reinstated.
ExpiredThe token has passed its expiration date. It cannot be used or reinstated.
  • Tokens are automatically marked as expired when used after their expiration date.
  • An API token's permissions are inherited from the user account for which it was generated. If the user's permissions change, the token reflects the current permissions.

Manage tokens​

On the API Tokens page (account icon > API Tokens), you can manage your existing tokens:

  • Revoke: Hover over a token row and click the Revoke action icon. This sets the token status to Inactive and it can no longer be used for authentication.
  • Reinstate: Hover over a previously revoked token row and click the Reinstate action icon. This reactivates the token, setting its status back to Active. Expired tokens cannot be reinstated.
  • Delete: Hover over a token row and click the Delete action icon to permanently remove the token.

Users can revoke, reinstate, and delete their own tokens. System administrators can revoke, reinstate, and delete tokens for any user.

Last updated on