Authentication

The Backwork API authenticates each request with an API key in the Authorization header. MCP clients use OAuth instead; see MCP Authentication.

Getting an API Key

Live keys are self-serve:

1. Sign up and create your organization. It starts with 100 free starter credits.
2. Open API usage and keys.
3. Under Live API keys, enter a name and choose Create live key.
4. Copy the key. Backwork shows the full key once and stores only its hash.

Only organization owners and admins can create and revoke keys. Every key in the organization spends the same request credits and shares one per-minute limit. See Pricing and credits for packs and the request cost of each endpoint, and the Quickstart for a first call.

Keys for GET /api/v1/releases/{releaseId}/decisions are separate from live keys: they carry only the certified:derived_decision:read scope and work only on that endpoint.

To try the API first, get a free sandbox test key. No account is needed:

curl -X POST https://backworkhealth.com/api/sandbox/v1/keys

See Try it in the sandbox.

Using Your API Key

Include your API key in the Authorization header using the Bearer scheme:

curl -X GET "https://backworkhealth.com/api/v1/health" \
  -H "Authorization: Bearer bwk_live_xxxx"

Key Format

API keys follow this format:

bwk_{mode}_{random}_checksum

• bwk - Prefix identifying Backwork API keys
• mode - Either live (production) or test (development)
• random - Cryptographically random string
• checksum - 4-character checksum for validation

Test vs Live Keys

The two key types do not overlap. Production routes reject test keys with AUTH_TEST_KEY_SANDBOX_ONLY, and the sandbox rejects live keys with AUTH_SANDBOX_TEST_KEY_REQUIRED. Test keys are self-serve and expire after 7 days.

Earlier API keys

Keys issued before the current bwk_ format start with vrt_. They still work. To rotate one, create a new live key in API usage and keys, move your integration to it, and revoke the old key.

API Key Scopes

Keys created in API usage and keys have the read scope. It covers every lookup, policy, coverage, prior-auth, claim, and compliance read endpoint, and the read-only agent tools.

Endpoints that change data require a key with the write or admin scope. The API usage page does not create write keys yet:

Use the narrowest scope each integration needs. The admin scope satisfies all read and write checks. GET /v1/webhooks also needs write, and every webhook endpoint needs the Scale pack.

MCP Authentication

Direct API integrations use API keys. MCP clients connect to the hosted server at https://backworkhealth.com/mcp with OAuth, so you do not copy a key into the client.

The OAuth flow signs the user in to Backwork, asks for consent to the read-only scopes backwork:mcp read, and issues a 1-hour access token for the MCP resource plus a rotating refresh token. The client uses the refresh token to get new access tokens for up to 30 days without a new consent. MCP requests spend the organization's request credits like any other API request, and are attributed to the signed-in user, the OAuth client, the organization, and the MCP tool.

See MCP Server for client setup.

Code Examples

The Go CLI and the examples on SDKs and HTTP clients read BACKWORK_API_KEY.

import requests
import os

response = requests.get(
    'https://backworkhealth.com/api/v1/health',
    headers={'Authorization': f'Bearer {os.environ["BACKWORK_API_KEY"]}'}
)

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "AUTH_KEY_NOT_FOUND",
    "message": "API key not found",
    "hint": "Check that your API key is correct",
    "docUrl": "https://backworkhealth.com/docs/errors#auth-key-not-found",
    "retryable": false
  }
}

Common Authentication Errors

See Error Handling for every code, its hint, and whether a retry can help.

Last updated on