Authentication

API keys, bearer tokens, and secure request authentication.

BSync Public API uses API key authentication. There is no OAuth flow and no token issuance endpoint.

OpenAPI: ApiKeyAuth security scheme — /docs/api-reference

API Keys

API keys are created in the BSync Dashboard under Settings → API Keys. Each key is shown only once at creation.

Prefix	Environment	Use
`bsync_test_*`	Test (sandbox)	Development and integration testing
`bsync_live_*`	Live (production)	Real payments

Test and live keys use the same API host (https://api.bsyncapp.com). The key prefix determines which environment your requests run in.

Authorization Header

Every authenticated request must include:

Authorization: Bearer {apiKey}

SDK (automatic):

import { BSync } from "@bsync/node-sdk";
 
const bsync = new BSync({ apiKey: "bsync_test_xxxxxxxx" });

curl:

curl https://api.bsyncapp.com/v1/payment-intents/pay_abc123 \
  -H "Authorization: Bearer bsync_test_xxxxxxxx"

Test vs Live

Aspect	Test (`bsync_test_*`)	Live (`bsync_live_*`)
API host	`https://api.bsyncapp.com`	`https://api.bsyncapp.com`
Payments	Sandbox — no real money	Real Vodafone Cash transactions
Webhooks	Delivered to your test endpoint	Delivered to your production endpoint
Data isolation	Test payments only	Live payments only

Using a test key against a live payment (or vice versa) returns 404 RESOURCE_NOT_FOUND (not ENVIRONMENT_MISMATCH) to avoid revealing whether a payment exists in another environment.

Key Rotation

Create a new API key in the Dashboard.
Update your server environment variable (BSYNC_API_KEY).
Deploy the change.
Revoke the old key once all services are updated.

Rotate keys periodically and immediately after any suspected compromise.

Key Revocation

Revoke keys in the Dashboard. Revoked keys return:

{
  "success": false,
  "error": {
    "code": "API_KEY_REVOKED",
    "type": "authentication_error",
    "message": "The provided API key has been revoked.",
    "requestId": "req_abc123",
    "details": {}
  }
}

HTTP status: 401

Security

Store API keys in environment variables or a secrets manager — never in source code or client-side code.
Use separate keys per service (checkout server, webhook processor, admin tools).
Grant least privilege: create keys with only the permissions each service needs.
Never expose keys in browser JavaScript, mobile apps, or public repositories.

See Security for the full security guide.

Error Codes

HTTP	Code	Type	When
401	`MISSING_AUTHORIZATION`	`authentication_error`	No `Authorization` header
401	`INVALID_AUTH_FORMAT`	`authentication_error`	Header is not `Bearer {key}`
401	`INVALID_API_KEY`	`authentication_error`	Key not found
401	`API_KEY_REVOKED`	`authentication_error`	Key was revoked
401	`API_KEY_EXPIRED`	`authentication_error`	Key has expired
403	`TENANT_INACTIVE`	`authorization_error`	Merchant account inactive
403	`INSUFFICIENT_PERMISSIONS`	`authorization_error`	Key lacks permission
404	`RESOURCE_NOT_FOUND`	`resource_error`	Cross-environment access (test key on live payment, or vice versa)

SDK error classes: AuthenticationError (401), AuthorizationError (403).

Was this page helpful?

Quick Start

Payment Intents