Agents

These are the calls an AI assistant or a command-line tool makes about itself: signing in, checking whether a person has approved something, and handing its own key back. None of them reads or changes anything in a workspace.

Signing in without pasting a key

A person should never have to copy a key out of a dashboard and into a config file. POST /v1/auth/device is the alternative, and it inverts who holds the secret:

1. Your program makes the key. Thirty-two random bytes, rendered as 43 base62 characters, with bc_live_ in front. Keep it somewhere only you can read.
2. You send its hash. key_hash is the SHA-256 of the whole string; key_prefix is the first 8 characters after bc_live_, which is what a person sees in their list of connections. The key itself has no field to travel in.
3. A person approves it at boltclaw.ai/auth/device, choosing the workspace and ticking the permissions they are willing to give.
4. You poll POST /v1/auth/device/poll every interval seconds until it answers approved. Then the key you already hold starts working.

denied and expired end it; start again. A device_code that was never issued, or has been cleared away, answers expired exactly like one that lapsed, so polling cannot be used to find out which codes exist.

The approval names the workspace the person chose, by id and name. That is one of the very few answers in this API that carries a workspace id, and it is answered only to the holder of the device_code: the program that started the sign-in, whose new key belongs to that workspace.

So between the approval and your next poll there is no credential of ours to lose, and a stolen device_code reveals one thing: whether the request was approved.

Do not try the key before the poll says approved. Until a person decides, that key does not exist, and it is refused exactly like any other key that does not — which the API remembers for five minutes, to make guessing keys expensive. A client that probes early therefore waits out those five minutes after the approval before anything works. Poll, and use the key once the poll tells you to.

Ask for the permissions you need and no more. The person sees the list, can untick any of it, and whatever survives is narrowed again to what they themselves may grant. Permissions an assistant may never hold — managing API keys, managing webhooks — are refused at step 1, not silently dropped at step 3.

Approvals

Some calls stop and ask. If you make one, you get a 428 whose body carries an approval object:

{
  "error": "Nothing has been done. A person must approve this action first...",
  "code": "APPROVAL_REQUIRED",
  "request_id": "...",
  "approval": {
    "id": "0c4b...",
    "url": "https://boltclaw.ai/dashboard/approvals/0c4b...",
    "expires_at": "2026-10-20T09:12:44.000Z",
    "status": "pending"
  }
}

Nothing has happened. Show the url to the person. When they approve it, send the identical request again with the id in the BoltClaw-Approval header. While you wait, GET /v1/approvals/{id} tells you where it has got to, and it is cheap enough to poll.

The approval is bound to that exact request and to the state it acts on, so one approved for deleting a page cannot be spent on a different page, or on the same page after somebody renamed it. It is single use and it lapses after 24 hours.

Which calls ask, and whether an organisation can decide to stop being asked, is on Authentication and keys.

Keeping a key alive, and ending it

A key approved for an assistant lasts 90 days. POST /v1/auth/key/extend pushes that out by another 90, up to a year from the day it was issued, and only within the last 30 days of its life — so calling it on a schedule is safe and usually answers extended: false. After a year, a person signs in again.

POST /v1/auth/key/revoke ends the calling key. Use it when somebody disconnects your program, and when you uninstall: deleting a key from a configuration file leaves it working, and this does not. It works even when an organisation has turned assistant access off, because handing a credential back must never be the thing you cannot do.

Both act only on the key that made the call, so neither needs a scope.

Operations

POST /v1/auth/device

Start a device sign-in

No scope: any valid key.

How an AI assistant or a command-line tool gets a key, without anybody pasting one.

Your program generates the key. Make 32 random bytes, render them as 43 base62 characters, prefix them with bc_live_, and send only the SHA-256 of the whole string plus the first 8 characters of the random body. The key itself must never leave the machine it was made on, and there is no field here that would carry it. BoltClaw stores the hash, exactly as it stores every other key's, so no secret of ours exists at any moment, not even between the approval and your next poll.

You get back a short code and a URL. Show both to the person, poll POST /v1/auth/device/poll every interval seconds, and once they approve, the key you already hold starts working.

Ask for the permissions you need and no more: the person sees them, can untick any of them, and the key is narrowed again to what they themselves may grant. Permissions an assistant may never hold, such as managing API keys or webhooks, are refused here rather than silently dropped later.

This call needs no API key, and it is limited per address rather than per key.

Request body (required)

{
  "client_name": "<client_name>",
  "scopes": [],
  "key_hash": "<key_hash>",
  "key_prefix": "<key_prefix>"
}

Answers

POST /v1/auth/device/poll

Poll a device sign-in

No scope: any valid key.

Has a person decided yet? Send the device_code from POST /v1/auth/device, no more often than interval seconds apart.

status is pending while you wait, slow_down if you are asking too fast (wait interval seconds and carry on), approved once a person has said yes, denied if they said no, and expired if nobody decided in time. A code that was never issued, or has been cleared away since, answers expired too, exactly like one that lapsed: the answer never tells you whether a code existed. Either way, start a new sign-in.

An approval answers with the key's id, its prefix, the permissions it ended up with and when it expires. It never answers with a key: you made it, so you already have it.

It also names the workspace the person chose, by id and name. Apart from GET /workspace and one route reserved for the BoltClaw MCP server, this is the only answer in the API that carries a workspace id, and it goes only to the holder of the device code: the program that started the sign-in, which is about to hold a key for that workspace and could read the same id with it.

This call needs no API key.

Request body (required)

{
  "device_code": "<device_code>"
}

Answers

GET /v1/approvals/{id}

Read an approval you asked for

No scope: any valid key. Another workspace's answers 404.

Has the person decided yet? This is the one thing a key may read about an approval, and only about its own: an approval another key asked for is 404, exactly like one that never existed.

You get the status and the deadline, not the summary: the summary was written for the person who decides, and you already know what you asked for. A pending or approved ticket past its deadline reads as expired.

Cheap and safe to poll while you wait, and left out of the agent call log so that waiting does not bury the calls that did something. Needs no scope.

Parameters

Answers

POST /v1/auth/key/extend

Extend the key you are using

No scope: any valid key. Accepts Idempotency-Key.

A key approved for an AI assistant lasts 90 days. Within 30 days of its expiry it can push that out by another 90, up to a year from the day it was issued, and then a person signs in again.

Nothing else can be extended this way: a key a person created in the dashboard has an expiry they chose, and this call will not second-guess it. The extension also stops if the person who approved the connection can no longer approve it, or if the organisation has turned AI assistant access off, which is what makes it safe to let a credential renew itself.

Acts only on the key that made the call, so it needs no scope. Safe to call on a schedule: outside the 30-day window it answers extended: false and changes nothing.

Answers

POST /v1/auth/key/revoke

Revoke the key you are using

No scope: any valid key. Accepts Idempotency-Key.

Sign out, for real. Deleting a key from a configuration file leaves it working; this ends it. Use it when a person disconnects your program, and when you are uninstalling.

Acts only on the key that made the call, so it needs no scope, and it works even when the organisation has turned AI assistant access off: handing a credential back must never be the thing you cannot do. It cannot be undone, and it is safe to repeat.

If the key is the root of a connection that spans several workspaces, every key in that connection ends with it.

Answers

POST /v1/auth/key/revoke-oauth

End a connection

No scope: any valid key.

Ends a whole AI connection, from its root, so no workspace is left reachable. Reserved for the BoltClaw MCP server; anything else is 404.

It takes a key ID rather than a key, because the MCP server reaches it exactly when it no longer holds one: a person signing the assistant out of their client revokes the grant whose encrypted store was the only copy of the key. The answer is the same for a key id that was a connection's root and for one that was never anything, so it tells a caller nothing about which ids exist.

This call needs no API key.

Request body (required)

{
  "key_id": "3f8c1e42-9b7a-4d61-a0f5-2c9e1b7d4a83"
}

Answers

GET /v1/auth/key/workspaces

List a connection's workspaces

No scope: any valid key.

Which workspaces this connection reaches today. Re-resolved on every call against the live permissions of the person who approved it, so a workspace they can no longer reach drops out with nothing to revoke. Reserved for the BoltClaw MCP server; anything else is 404.

Answers

POST /v1/auth/key/workspaces

Register a connection's workspace

No scope: any valid key. Accepts Idempotency-Key.

Registers the key for one workspace of a connection, from a hash the caller derived and a prefix to display. Creates nothing if that workspace already has a live key, and answers the one it has. Reserved for the BoltClaw MCP server; anything else is 404.

Request body (required)

{
  "workspace_id": "3f8c1e42-9b7a-4d61-a0f5-2c9e1b7d4a83",
  "key_hash": "<key_hash>",
  "key_prefix": "<key_prefix>"
}

Answers

Shapes

The objects these operations send and answer.

ApprovalAction

What an assistant asked to do. The actions in the first group are the ones an organisation may decide to stop being asked about, or waive for one connection for a few hours; the rest are always asked, because they move somebody else's money or change somebody else's access.

One of: post.publish, post.delete, inbox.reply, inbox.hide, conversation.reply, automation.enable, automation.delete, page.delete, page.unpublish, link.delete, lead.delete, referral.payout.paid, referral.commission.adjust, referral.partner.approve, social.account.disconnect, referral.commission.bonus, referral.reward.delete, referral.group.delete, referral.referrer.erase, referral.grant.fulfil, referral.grant.fail, referral.stripe.codes, referral.testdata.clear, referral.flag.dismiss, referral.flag.confirm, referral.risk.update, referral.payout.send, referral.payout.settings, referral.commission.forfeit, referral.tax.settings, referral.brand.update, referral.domain.add, referral.domain.remove, referral.listing.update, referral.library.delete, referral.broadcast.send, referral.import.commit, referral.contest.award, referral.contest.cancel, referral.waitlist.disqualify, referral.waitlist.invite, referral.tier.update, referral.waitlist.end, referral.waitlist.forget, referral.shopify.codes, referral.terms.update, referral.subject.erase, referral.program.archive, referral.partner.ban, referral.partner.unban, referral.commission.approve, referral.code.create, referral.link.archive, referral.program.restore, referral.signup.rotate, referral.waitlist.rotate, referral.embed.rotate, referral.referrer.approve, referral.code.link, referral.payout.reopen.

ApprovalStatus

ConnectionRevoke

ConnectionWorkspaceKey

ConnectionWorkspaceList

Answered only to the BoltClaw MCP server, which keeps one key per workspace of a connection and needs each workspace's id to do it. Anything else asking is answered 404.

ConnectionWorkspaceRegister

DeviceAuthorization

DeviceAuthorizationPoll

DeviceAuthorizationStart

The key is made on your machine and never sent. key_hash is the SHA-256 of the whole bc_live_... string, as 64 lowercase hex characters; key_prefix is the first 8 characters of the random body after the prefix, and is what a person sees in the list of connections.

DeviceAuthorizationStatus

pending while you wait, slow_down if you are asking too fast, approved once a person has said yes, denied if they said no, expired if nobody decided in time. A code that was never issued answers expired as well, so the answer never says whether one existed.

KeyExtendResult

KeyRevokeResult

NextCursor

Pass back as cursor for the next page; null on the last page.

string | null.