API Authentication

Betterstore API routes use bearer-token authentication. Most /api/* routes use organization API secrets and attach organization/testmode context before handlers run.

Client checkout routes are separate and use checkout secrets for customer-facing checkout flows.

Header

Send the API secret in the Authorization header:

curl https://api.example.com/api/products/find-many \
  -H "Authorization: Bearer $BETTERSTORE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

Context

Authenticated requests should resolve:

• the organization that owns the secret,
• whether the request runs in test mode,
• route-specific authorization context.

Error handling

API routes are defined with OpenAPI metadata and standard error responses. Invalid bodies or path parameters return validation errors. Missing or invalid credentials return authentication errors before business logic runs.

Security expectations

• Do not expose API secrets in browser code.
• Do not reuse checkout secrets for admin API routes.
• Rotate leaked API secrets immediately.
• Keep server-side logging free of raw secrets, payment details, and customer-sensitive data.