data envelope. Read the response envelope before you write a client.
Base URL
POST /sdk/create-session is POST https://api.botshield.ai/operations/sdk/create-session. Send and accept application/json. GET operations take their input as query parameters.
Development and Production share the base URL. The credential you send selects the environment, and a gate is looked up in the environment of the key that calls it: bs_dev_… and pk_test_… keys reach Development gates (the Console dashboard calls this your sandbox), and bs_production_… and pk_live_… keys reach Production gates. The same gate key can exist in both environments, as two separate gates. A key whose environment has no Active gate with that gate key gets an error.
Send the gate key as gate. The older name scope is still accepted until 2027-01-15, and responses carry both. See Alias window.
Credentials
Send the credential as a bearer token:Authorization: Bearer <credential>.
See Keys and environments for how to create, rotate, and revoke keys.
Which operation takes which credential
The response envelope
Every operation answers HTTP 200 with a JSON object that has a top-leveldata property.
- Success. Most operations nest the result once more, so you read
data.data. Two operations return the result directly underdata:GET /verification/statusandPOST /sdk/logout. - Failure. An operation that rejects your request still answers HTTP 200. The error is at
data.error, anddata.error.statusCodeholds the status the error stands for (401,403,404,409, and so on).
data.error before you read the result.
RATE_LIMITED when you exceed a rate limit, and HTTP 500 for an unhandled failure. One rate-limit case stays inside the envelope: a development key’s limit on create-verification-link arrives as data.error with statusCode 429 and code: "RATE_LIMITED". Errors covers each shape and includes a helper that handles all of them.
Worked example
census is the SDK’s name for BotShield Gate.)
For the two operations that are not double-nested, read the fields from data itself:
status is one of pending, completed, pass, expired, failed, not_found, or error. Two values mean the human is verified: completed (the human confirmed on their phone) and pass (a success recorded without a new confirmation on the phone, where the widget reports success with token: null). A pass record reads expired 60 seconds after the check, so call this operation as soon as the widget reports success. Never test for completed alone.
When status is failed, reason says why when BotShield knows: pass_limit_reached or real_days_not_met when the gate’s Who may pass rules refused the person, already_trusted or rebind_requires_prior_id when a Verified Accounts link was refused, and unavailable otherwise. Treat every failed as Unavailable.
Operations
BotShield Gate
POST /sdk/create-session: open a five-minute, single-use grant and get abss_…grant token.POST /sdk/create-verification-link: create a verification request for a gate and get itsrequest_id, its links, and itsexpires_at.expires_atis the request’s own expiry, five minutes after creation, and is the same instantGET /verification/statusreports for that request.GET /verification/status: read the current status of a verification request.POST /sdk/verify-token: validate an attestation token and read its claims. Send your Organization ID asaudience: a token issued for another organization then returnsvalid: false. Copy it from the Console under Settings → Developer Tools → API Keys; the create-session response also returns it asorganization.id. Calling with your API key instead sets the audience to your key’s organization. Each token is good for one check: a repeat check returnsvalid: falsewithreplayed: true. Still compareclaims.request_idwith the request you started.POST /sdk/revoke-verification: end the pending requests one user has for a gate, so a new one can be created. Returnsrevoked_count.POST /sdk/logout: revoke an unused grant token.
Gates API
Place and run gates and BotShield Actions from your server. Every call needs an API key with thegates:write scope; without it the call answers gates_scope_required. See Gates API.
POST /gates-api/create,POST /gates-api/activate,POST /gates-api/extend,POST /gates-api/close,POST /gates-api/cancel,GET /gates-api/get,GET /gates-api/list: the gate lifecycle.POST /gates-api/actions/create,GET /gates-api/actions/list,POST /gates-api/actions/set-state: place and turn BotShield Actions on and off.POST /gates-api/actions/request,GET /gates-api/actions/request-status: start an action request for a user and read its outcome.
Verified Accounts
The paths keep the older namesecured-accounts. See Server API.
GET /secured-accounts/status: whether one of your user IDs is linked right now (none,freshorstale).GET /secured-accounts/list: your registry, by handle, for the key’s environment.POST /secured-accounts/revoke: unlink one account, byplatform_user_reforhandle, withreason: "platform"or"credential_changed".
Agents Ask
POST /agent/bind-session: start linking a human to your agent and get a link code.GET /agent/check-binding: check whether the human claimed the code, and receive theiropaque_id.POST /agentlink/inquire: propose an action for the human to Confirm or Deny.GET /agentlink/check-status: read the outcome of a proposal. Supports a long-poll of up to 25 seconds.POST /agentlink/cancel: withdraw a proposal that is still waiting.
Verify signatures locally
BotShield signs attestation tokens and Proofs of Resolution with ES256. The public keys are published as a standard JWKS:data envelope, with Cache-Control: public, max-age=300. Cache it for five minutes and select the key by the kid in the token header. If the key set cannot be built, the URL answers HTTP 503 with {"keys": [], "error": "jwks_unavailable"}. Keep using your cached copy and retry.
Tokens are issued with iss set to https://api.botshield.ai. See Verify on your server for attestation tokens and Proof of Resolution for Agents Ask.
Next steps
Errors
Every error shape, status code, and a typed unwrap helper.
Rate limits
Limits by key type and how to back off.
TypeScript SDK
Call the API with typed methods.
Keys and environments
Create and manage the credentials on this page.
