Authentication

Authenticate REST requests with a Bearer personal access token and the blue-org-id header.

The Blue REST API authenticates every request with a personal access token (PAT) sent as a Bearer token, plus a blue-org-id header that scopes the request to one organization. These are the same tokens the GraphQL API and the MCP server use - a token belongs to a user and inherits that user’s permissions.

Authenticate a request

Send two headers on every request:

curl https://rest.blue.app/v1/list-workspaces \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "blue-org-id: YOUR_ORG_ID" \
  -d '{}'
HeaderRequiredDescription
AuthorizationYesBearer <token> - your personal access token.
blue-org-idYesThe organization to act in. Scopes the request to that org’s data.
Content-TypeFor writesapplication/json on any request that carries a JSON body.

Header names are case-insensitive. The blue-org-id value is the organization’s ID.

Legacy header still works

blue-org-id was previously named x-bloo-company-id (and the GraphQL API’s X-Bloo-Company-ID). Both legacy names are still accepted, so existing integrations keep working without changes. Use blue-org-id for anything new.

Create a token

Tokens are created in Blue’s settings, not via the API.

  1. Open Blue and click your profile avatar in the top-right corner.
  2. Choose API from the profile menu.
  3. Click Generate a Token.
  4. Give the token a name, and optionally set an expiration date.
  5. Click create. Blue shows you the token once.
The token is shown only once

Blue stores the token as a hash, so it cannot be retrieved after creation - not even by Blue’s team. Copy it somewhere safe the moment it’s shown. If you lose it, delete the token and create a new one. Anyone with the token can act as you in Blue, so treat it like a password and never commit it to source control.

The same token works across the REST API, the GraphQL API, and the MCP server - there’s no separate REST credential to manage.

Find your organization ID

The blue-org-id value names the organization (a Company in the API) the request acts in. Every request must carry it - it’s how Blue knows which org’s records, workspaces, and settings you’re reaching for. You can find it in the app, or list the organizations a token can reach and read their IDs from the response.

Authentication errors

The API returns a JSON { "error": ... } body with one of these statuses when a request can’t be authenticated or authorized:

StatusCodeWhen
400Bad RequestThe blue-org-id header (or a legacy alias) is missing from the request.
401UnauthorizedThe token is missing, malformed, expired, or doesn’t match a real token.
403ForbiddenThe token is valid but the user has no access to the organization named in the header.

A missing or bad Bearer token returns 401:

{
  "error": "Unauthorized"
}

A valid token whose user can’t reach the requested organization returns 403:

{
  "error": "User does not have access to this company"
}

The distinction matters: 401 means “we don’t know who you are” - check the token. 403 means “we know who you are, but you can’t act here” - check that the user is a member of the organization you passed in blue-org-id. See Errors & Rate Limits for the full status table.