Connect your AI agent

Overview

Most Bland integrations start with a human signing up in the dashboard, minting an API key, and pasting it into whatever they’re building. That doesn’t work well for an autonomous bot: there’s no dashboard session to sign into, and often no browser or localhost to redirect back to. Agent onboarding solves this with a device-authorization flow, the same shape used by tools like gh auth login or a smart TV signing into a streaming app: the bot starts the flow over a plain API call, shows its owner a short code and a link, and polls in the background while the owner finishes signup and subscribes in their own browser. No callback URL, no localhost, no client secret. It works the same way whether the bot is running on your laptop or on a server with no browser at all. At the end of the flow, the bot receives a dedicated API key and the phone number provisioned for it. The owner never sees or handles the key.

This flow signs the owner up for the Agent Phone Plan. If the owner already has a Bland account, they sign in and subscribe instead of creating a new one.

The flow

Start the flow

Call POST /v1/agent/onboarding/start. No API key is required, this is how a bot gets one.

curl -X POST https://api.bland.ai/v1/agent/onboarding/start \
  -H "Content-Type: application/json" \
  -d '{"client_name": "my-bot"}'

Response

{
  "data": {
    "device_code": "Xk9pQ2mZ...",
    "user_code": "BQPL-7VXR",
    "verification_url": "https://app.bland.ai/agent-setup",
    "verification_url_complete": "https://app.bland.ai/agent-setup?code=BQPL-7VXR",
    "expires_in": 900,
    "interval": 5
  },
  "errors": null
}

client_name is optional (up to 64 characters, letters, numbers, spaces, and ._/-). It’s shown to the owner so they know which bot is asking.

Show the link and code to your owner

Display verification_url_complete (or verification_url plus user_code if you can’t render a clickable link) wherever your owner will see it: a chat message, a terminal, a Slack DM.The owner opens the link, signs up or logs in, enters the code if it isn’t already pre-filled, and subscribes to the Agent Phone Plan. This happens once, in their browser. Your bot doesn’t participate in it beyond polling for the result.

Poll until approved

Call POST /v1/agent/onboarding/poll with the device_code, waiting at least interval seconds between calls.

curl -X POST https://api.bland.ai/v1/agent/onboarding/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "Xk9pQ2mZ..."}'

Each response has a status:

`status`	Meaning
`pending`	Still waiting on the owner. Keep polling at the returned `interval`.
`approved`	Onboarding is complete. The response includes `api_key`, `org_id`, and `phone_number`.
`expired`	The code expired, or the `device_code` was never valid. These two cases aren’t distinguished, so don’t use `expired` to debug a typo, start over with a fresh `/start` call instead.

If you poll faster than interval, you get a 429 with error code SLOW_DOWN instead of a status:

429 SLOW_DOWN

{
  "data": null,
  "errors": [
    {
      "error": "SLOW_DOWN",
      "message": "Poll more slowly.",
      "interval": 10
    }
  ]
}

Back off to the interval in the error body (also sent as a Retry-After header) before polling again.

Use the key

Once status is approved, the response looks like this:

Response

{
  "data": {
    "status": "approved",
    "api_key": "org_...",
    "org_id": "...",
    "phone_number": "+14155550123",
    "plan": {
      "name": "agent_phone_basic",
      "display_name": "Agent Phone Plan",
      "status": "active",
      "phone_number": "+14155550123",
      "concurrency": 1,
      "max_call_duration_minutes": 60,
      "allowed_countries": ["US", "CA"],
      "current_period_end": "2026-10-07T00:00:00.000Z"
    },
    "client_name": "my-bot"
  },
  "errors": null
}

This is the only time api_key is returned. Store it immediately, the code is single-use, so polling again after this returns expired.

The device flow is region-bound. Start and poll must target the same API host the owner’s dashboard uses. For most accounts that is https://api.bland.ai, paired with https://app.bland.ai. Regional dashboards pair with a regional API host: eu.app.bland.ai with eu.api.bland.ai, ca.app.bland.ai with ca.api.bland.ai, and both asia.app.bland.ai and au.app.bland.ai with asia.api.bland.ai. If poll returns expired right after the owner told you they approved, check the host pairing first.

Try it with a client

cURL
bland-cli
bland-skills

Use the two calls above directly: POST /v1/agent/onboarding/start, then poll POST /v1/agent/onboarding/poll with the returned device_code until status is approved.

The Bland CLI wraps the whole flow in one command:

bland auth login --device

bland signup is an alias for the same command, if you don’t have an account yet.It prints the link and code, polls for you, and stores the resulting API key in your CLI profile once approved. See Getting started.If you pass --base-url, it must match the owner’s dashboard region.

Agents built with bland-skills (for example, running inside Claude Code) use two tools:

bland_auth_login with mode "device" starts the flow and returns the link and code to show your owner.
bland_auth_poll polls until the flow is approved and returns the API key.

The key is handled by the tool call result, not printed to the conversation.

Error codes

Code	HTTP status	Where	Meaning
`SLOW_DOWN`	429	`/poll`	Polling faster than `interval`. Back off and retry.
`TOO_MANY_REQUESTS`	429	`/start`, `/poll`, `/approve` (browser)	Rate limited. Respect the `Retry-After` header and retry.
`FEATURE_DISABLED`	503	`/start`	Agent onboarding is temporarily disabled. Retry later.
`PLAN_REQUIRED`	402	`/approve` (browser)	The org doesn’t have an active Agent Phone Plan subscription yet.
`PLAN_NUMBER_PENDING`	409	`/approve` (browser)	The plan is active but the phone number is still being provisioned.
`CODE_NOT_FOUND`	404	`/approve` (browser)	The code doesn’t exist or already expired.
`CODE_ALREADY_USED`	409	`/approve` (browser)	The code was already approved.
`ORG_CONTEXT_REQUIRED`	403	`/approve` (browser)	The signed-in account isn’t acting as an org, so it can’t approve a device code.
`INVALID_ORIGIN`	403	`/approve` (browser)	The approve request did not come from the Bland dashboard.

The /approve codes happen in the owner’s browser during signup, your bot only ever sees their effect: poll staying pending for longer than expected, or eventually returning expired.

Security notes

Codes expire in 15 minutes. If the owner doesn’t finish in time, start over with a new /start call.
Codes are single-use. The first successful poll after approval returns the api_key and consumes the code. Any poll after that returns expired.
The API key is scoped to that org and can be revoked at any time from Settings > API Keys in the dashboard, without affecting any other keys on the account.
Each approval mints a new key. Running onboarding again for the same org creates another org key rather than reusing one, so the list in Settings > API Keys grows by one per connected agent. Revoke the ones you no longer use.
Treat the returned api_key like a password: store it in your bot’s secret storage, not in logs or chat transcripts.

MCP requires an API key. If your agent talks to Bland over MCP, use the api_key from this flow the same way you’d use any other Bland API key.

Next steps

Agent Phone Plan

What’s included, limits, and how to cancel.

Command Line Interface

bland auth login --device and the rest of the CLI.

Docs for agents: llms.txt

Welcome

Core Bland Features

MCP & AI Agents

Basic Tutorials

Advanced Features

Platform Information

SDKs & Tools

Bland Enterprise

Connect your AI agent

Overview

The flow

Try it with a client

Error codes

Security notes

Next steps

Agent Phone Plan

Command Line Interface

​Overview

​The flow

​Try it with a client

​Error codes

​Security notes

​Next steps

Agent Phone Plan

Command Line Interface

Overview

The flow

Try it with a client

Error codes

Security notes

Next steps