Authentication

Resource requests to the BenchKey API require an API key. API access requires the Business plan and must be enabled for your environment. An authorized workspace administrator creates keys in Settings and can set an expiry or revoke them. The service metadata, health, and OpenAPI endpoints do not require a key.

API key format

Every key begins with a prefix that identifies its mode:

Prefix	Mode	When to use
bk_live_	Live	Production requests that affect real data
bk_test_	Test label	Labels an integration key; accesses the same workspace data as a live key

A live key looks like:

bk_live_42_kvWz9nP3mRqTs7uYeBfGhDjLa0123456789ABCD

A test label does not create a sandbox. Both key prefixes access the tenant encoded in the key. Writes with a bk_test_ key can change that workspace’s real records and trigger its normal side effects. Use a separate workspace with fictional data for development, and confirm its identity with GET /api/v1/me before writing.

Creating an API key

1. Go to Settings → API keys in BenchKey.
2. Click Create key.
3. Enter a Name (e.g., My Integration), choose the Environment label, and set Expiration.
4. Choose the Scopes your integration needs, only grant what you actually use, then select Create key.
5. Copy the key immediately. For security, the full secret is shown only once.

If you lose a key, revoke it and create a new one.

Authenticating requests

Pass your API key as a Bearer token in the Authorization header:

Authorization: Bearer bk_live_42_kvWz9nP3mRqTs7uYeBfGhDjLa0123456789ABCD

curl

curl https://app.benchkey.com/api/v1/me \
  -H "Authorization: Bearer bk_live_42_kvWz9nP3mRqTs7uYeBfGhDjLa0123456789ABCD"

Node.js (fetch)

const res = await fetch("https://app.benchkey.com/api/v1/me", {
  headers: {
    Authorization: "Bearer bk_live_42_kvWz9nP3mRqTs7uYeBfGhDjLa0123456789ABCD",
  },
});
const data = await res.json();

Scopes

Each API key carries a set of scopes that limit what it can do. A scope takes the form <resource>.<read|write>, read grants list/retrieve, write grants create/update/delete and action endpoints. Every endpoint’s reference page states the scope it requires.

The full catalog:

Scopes	Covers
account.read / account.write	Account profile
appointments.read / appointments.write	Appointments, including slots
assets.read / assets.write	Assets (customer devices)
billing.read / billing.write	Billing (your BenchKey subscription)
canned_responses.read / canned_responses.write	Canned responses
customers.read / customers.write	Customers
estimates.read / estimates.write	Estimates
files.read	Files (read-only)
inventory.read / inventory.write	Inventory stock levels
invoices.read / invoices.write	Invoices
leads.read / leads.write	Leads, plus the lead status registry
locations.read / locations.write	Locations
memberships.read / memberships.write	Memberships plans and enrollments
messages.read / messages.write	Messages and conversations
notifications.read / notifications.write	Notifications
payments.read / payments.write	Payments
products.read / products.write	Products
purchase_orders.read / purchase_orders.write	Purchase orders
reports.read	Reports (read-only)
reviews.read / reviews.write	Reviews
services.read / services.write	Services
settings.read / settings.write	Settings
shipments.read / shipments.write	Shipments
store_credit.read	Store credit (read-only)
tags.read / tags.write	Tags
tax.read / tax.write	Tax classes
team.read / team.write	Roles discovery, plus team-member profile/role updates
tickets.read / tickets.write	Tickets, plus the status catalog and queues
timeclock.read / timeclock.write	Timeclock shifts and payroll
users.read / users.write	Users (team roster)
vendors.read / vendors.write	Vendors
warranty.read / warranty.write	Warranty claims
webhooks.read / webhooks.write / webhooks.manage	Webhooks, manage additionally allows rotating signing secrets

If a request is made with a key that lacks the required scope, the API returns 403 Forbidden with error code insufficient_scope. Note that webhook subscriptions are additionally scope-gated by the read scope of each event family they subscribe to.

Test vs. live mode

Use a dedicated development workspace and a key with only the scopes needed for the task. Changing a key’s prefix does not change its data destination. Before a production cutover, verify the tenant returned by GET /api/v1/me and the granted scopes.

The response’s BenchKey-Version identifies the API implementation in both modes; sending the header does not select an older implementation.

Security best practices

• Never expose keys client-side. API keys carry your shop’s full permissions for the scopes they hold. Never embed them in browser JavaScript, mobile apps, or public repositories.
• Use the minimum scopes needed. Create separate keys for separate integrations, each with only the scopes it requires. This limits blast radius if a key is compromised.
• Rotate keys periodically. Revoke old keys from Settings and issue new ones. The API will return 401 Unauthorized for revoked keys immediately, no propagation delay.
• Store keys in environment variables. Never hardcode them in source files.

.env

BENCHKEY_API_KEY=bk_live_42_kvWz9nP3mRqTs7uYeBfGhDjLa0123456789ABCD

const apiKey = process.env.BENCHKEY_API_KEY;

Account status

Even with a valid key, requests are blocked when your account has a billing or suspension problem:

HTTP status	Error code	Meaning
402	billing_subscription_required	The tenant’s subscription is inactive (past-due, canceled, or no active plan). details includes billing_required, reason, subscription_status, and current_period_end. Restore billing to resume API access.
503	tenant_suspended	The account has been administratively suspended. API access is unavailable until the account is reinstated.

These errors fire after authentication succeeds, the key itself is valid.

Error responses

HTTP status	Error code	Meaning
401	unauthorized	Key is missing, malformed, or revoked
402	billing_subscription_required	Subscription inactive, see Account status
403	insufficient_scope	Key lacks the required scope for this endpoint
503	tenant_suspended	Account suspended, see Account status

See Errors for the full error envelope format.