Calling the API with OAuth tokens

Once you have an OAuth access token, call the Blooio API exactly as you would with an API key — pass the token as a bearer token:

Authorization: Bearer blo_at_...

Selecting the organization

An access token is bound to your app and the user who authorized it, and that user may have installed your app on multiple organizations. Tell Blooio which org a request targets with the X-Organization-Id header:

curl -X POST https://api.blooio.com/v4/messages \
 -H "Authorization: Bearer blo_at_..." \
 -H "X-Organization-Id: org_..." \
 -H "Content-Type: application/json" \
 -d '{ "to": "+15551234567", "text": "Hello from our app!" }'

• If the user installed your app on exactly one organization, the header is optional and that org is used.
• If they installed it on several, X-Organization-Id is required — omitting it returns 400.
• The org must be one the token's user actively installed your app on, or the request returns 403.

Scope enforcement

OAuth requests are default-deny: a token can only reach endpoints covered by the scopes the user granted. Calling an endpoint you don't have a scope for returns 403 with a message naming the required scope. Requesting more scopes later requires the user to re-authorize (see OAuth authorization).

Errors

• 401 — missing, expired, or revoked token. Refresh it, or re-run the authorization flow.
• 403 — the token lacks the required scope, or the target organization isn't an active install.
• 400 — X-Organization-Id is required because the token resolves to more than one installation.

Differences from API keys

• API keys belong to one organization; OAuth tokens belong to your app + a user and choose the org per request via X-Organization-Id.
• API keys have all permissions on their org; OAuth tokens are limited to granted scopes.
• Everything else — endpoints, request/response shapes, idempotency, pagination — is identical.