Authentication, permissions, and errors | AtomicPay API Reference

How to authenticate requests, understand permissions, rate limits, and handle API errors.

Base URL

Production requests use https://api.atomicpay.com.br. Local testing can use your Wrangler dev URL.

Authentication

Use either Authorization: Bearer <API_KEY> or X-API-Key: <API_KEY>. API keys must start with atpay_. Never expose these keys in browser code.

Permissions

API keys can be account-scoped or product-scoped. Product-scoped keys only return data for their product. Wildcard keys (*) can call every endpoint.

Available permission names

purchases.read, customers.read, products.read, subscriptions.read, subscriptions.write, charges.write, customers.write, cards.write, cards.read.

Rate limits

Each API key is limited to 100 requests per minute. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Error format

error.json

{
  "error": {
    "code": "unauthorized",
    "message": "No API key provided. Use Authorization: Bearer <key> or X-API-Key: <key>.",
    "type": "authentication_error",
    "status": 401
  }
}

Health endpoints

GET / returns the API name, version, docs URL, and operational status. GET /v1 returns the current API version and docs URL. These endpoints do not require authentication.