Docs
BetaThe V4 API is in beta — endpoints and functionality may change.

API key lifecycle

Create API keys, assign them to channels, route with priorities, and revoke — from the dashboard or programmatically via a Blooio App.

An API key authenticates direct calls to the Blooio API as a bearer token (Authorization: Bearer <key>). This page walks the full lifecycle of a key: create → assign channels → route with priorities → send → deprecate.

API keys vs. app tokens

An API key is not the same as a Blooio App (OAuth) access token (blo_at_...). An app token acts on behalf of an installing organization under scoped consent; an API key is a long-lived credential the org uses for its own server-to-server calls. The management endpoints on this page (create, assign, deprecate) are callable only with an app token — see Scopes & who can manage keys.

1. Create a key

There are two ways to mint a key:

From the dashboard

Create and revoke keys in the Blooio dashboard under Developers → API keys. This is the right path for a team managing its own integration.

Programmatically (Blooio Apps only)

An installed Blooio App that was granted the apikeys:manage scope can mint keys for the organization it is acting on. This is how a platform provisions a dedicated key per customer without a human in the loop.

curl -X POST https://api.blooio.com/v4/api-keys \
 -H "Authorization: Bearer blo_at_..." \
 -H "Content-Type: application/json" \
 -d '{ "name": "Acme production" }'
Try it

The response returns the new key once — store it securely:

{
 "data": {
 "api_key": "api_...",
 "name": "Acme production",
 "type": null,
 "created_at": 1735689600000,
 "valid_until": -1,
 "blocked": false,
 "deprecated": false
 }
}

valid_until is epoch milliseconds, or -1 for a key that never expires. Organizations have a fixed ceiling on active keys; exceeding it returns 409 api_key_limit_reached.

Only app tokens can create keys. Calling POST /v4/api-keys with a plain API key (or dashboard session) is rejected with 403 oauth_token_required. A key can never mint sibling keys — that would be a privilege-escalation and lifecycle-loop hazard.

2. Assign channels (numbers) to the key

A fresh key owns no numbers, so it can't send yet. You give a key sending power by making it the owner of one or more channels (a channel is a numbered sender — a Blooio line, a Twilio line, etc.). This is the same ownership you set by dragging numbers onto a key on the dashboard Channels board.

Assign a channel with a Blooio App:

# {channel} accepts the same references as "from": a phone number
# (URL-encode + as %2B), a channel alias, or an exact ch_ id.
curl -X PUT "https://api.blooio.com/v4/api-keys/api_.../channels/%2B15551230001" \
 -H "Authorization: Bearer blo_at_..."
Try it
{
 "data": {
 "api_key": "api_...",
 "channel_id": "ch_...",
 "address": "+15551230001",
 "success": true,
 "reassigned": false
 }
}

Key rules:

  • Sole ownership — assigning a line that another key or integration owned transfers it (the previous owner is released, and its hybrid mode re-evaluated). reassigned: true flags a transfer.
  • Idempotent — re-assigning a line the key already owns is a no-op (unchanged: true).
  • Number-pool plans — on plans without number pools a key may own at most one line; a second assignment returns 400.
  • Assignable types — only numbered, key-ownable channels (Blooio lines, and Twilio where applicable) can be assigned. Non-numbered types (WhatsApp, RCS Business) return 422 channel_not_assignable.

Inspect what a key owns at any time:

curl "https://api.blooio.com/v4/api-keys/api_.../channels" \
 -H "Authorization: Bearer blo_at_..."
Try it

Remove a line with DELETE /v4/api-keys/{apiKey}/channels/{channel}.

3. Order the key's channels with priorities

Ownership decides which numbers a key can use; a priority decides the order Blooio walks them when you send without an explicit from. Each key has one default priority (the dashboard Channels board edits it), plus optional named priorities addressed by priority_id.

  • Same-tier, same-type channels form a sticky pool.
  • Different tiers form a waterfall (try tier 1, then tier 2…).
  • With no priority configured, a key falls back to an implicit pool of the Blooio numbers it owns.

See Priorities and Channels & senders for the routing model in depth.

4. Send with the key

Once a key owns at least one channel, authenticate the send with that key. Omit from and Blooio routes across the key's owned numbers via its priority:

curl -X POST https://api.blooio.com/v4/messages \
 -H "Authorization: Bearer api_..." \
 -H "Content-Type: application/json" \
 -d '{ "to": "+15557654321", "text": "Hello from Blooio!" }'
Try it

Pin a specific owned line with "from": "+15551230001" (see Message sending).

5. Deprecate the key

Revoke a key when it's no longer needed. Deprecation stops the key authenticating immediately and releases its number ownership:

curl -X DELETE https://api.blooio.com/v4/api-keys/api_... \
 -H "Authorization: Bearer blo_at_..."
Try it

Deprecation is idempotent and can't be undone via the API — mint a new key instead.

Scopes and who can manage keys

Every management endpoint is Blooio Apps (OAuth) only. API-key and dashboard authentication are rejected with 403 oauth_token_required.

Operation Endpoint Scope
List / get keys GET /v4/api-keys, GET /v4/api-keys/{apiKey} apikeys:read
Create a key POST /v4/api-keys apikeys:manage
Deprecate a key DELETE /v4/api-keys/{apiKey} apikeys:manage
List a key's channels GET /v4/api-keys/{apiKey}/channels apikeys:read
Assign / unassign a channel PUT/DELETE /v4/api-keys/{apiKey}/channels/{channel} apikeys:manage

Request these scopes when you register your app; the organization grants them on the consent screen.