Skip to main content
Backside.app uses dual-rail authentication. Every request must include either a Bearer API key or an x402 payment receipt. If neither is present, the API returns 402 Payment Required with payment options.

​
API keys (developers)

Pass your key in the Authorization header: 
Authorization: Bearer bsk_live_<key>

​
Key format

EnvironmentPrefixExample
Productionbsk_live_bsk_live_a1B2c3D4...
Testbsk_test_bsk_test_x9Y8z7W6...
Keys are 52 characters total: 9-character prefix + 43 random alphanumeric characters.

​
Key management

OperationEndpointMethod
Create key/api/v1/api-keysPOST
List keys/api/v1/api-keysGET
Get key/api/v1/api-keys/{id}GET
Rotate key/api/v1/api-keys/{id}/rotatePOST
Revoke key/api/v1/api-keys/{id}DELETE

​
Key rotation

Rotate a key to get a new secret while preserving the key’s metadata, scopes, and audit trail. The old key is immediately revoked and a new one is returned. 
curl -X POST https://api.backside.app/api/v1/api-keys/{id}/rotate \
  -H "Authorization: Bearer bsk_live_your_key_here"
The response includes the new raw key. Store it immediately — it cannot be retrieved again.

​
Scopes

Keys can be scoped to limit access. A key with null scopes has full access. Scoped keys use the format domain:action: 
{
  "name": "Read-only contacts",
  "scopes": ["contacts:read", "crm:read"]
}
If a request requires a scope the key doesn’t have, the API returns 403 Forbidden.

​
Key security

  • Keys are hashed with SHA-256 before storage. The raw key is never persisted.
  • Keys are shown once at creation. They cannot be retrieved again.
  • Revoked keys are immediately unusable.
  • Key usage is tracked via last_used_at.
  • All key operations are recorded in the audit log.

​
x402 payments (agents)

AI agents can pay per-request with USDC on Base. No account, no API key required. Pass the x402 payment receipt in the PAYMENT-SIGNATURE header: 
PAYMENT-SIGNATURE: <x402 receipt>
The first payment from a new wallet auto-provisions a tenant. See x402 payments for the full protocol.

​
Error responses

StatusMeaning
401 UnauthorizedInvalid, expired, or revoked API key
402 Payment RequiredNo credentials provided — includes payment options in response
403 ForbiddenValid key, but missing required scope