Authentication

All Paygate API requests require a Bearer token in the Authorization header. There are two types of tokens.

API Keys (recommended)

API keys are long-lived credentials for server-to-server calls. They come in pairs — a public key and a secret key.

Use the secret key as your Bearer token:

curl https://paygate-api.fly.dev/v1/charges \
  -H "Authorization: Bearer sk_test_abc123..."

Generating a key pair

POST /v1/me/api_keys
Authorization: Bearer <jwt_token>

The response includes a secret_key field. This is the only time the secret key is returned. Store it immediately in a secrets manager or environment variable.

Revoking a key

DELETE /v1/me/api_keys/:id
Authorization: Bearer <sk_test_...>

Revoked keys return 401 Unauthorized on all subsequent requests.

JWT Session Tokens

JWT tokens are issued at login and intended for dashboard sessions — not for API integrations.

POST /v1/auth/login
Content-Type: application/json

{
  "email": "acme@example.com",
  "password": "supersecret"
}

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "merchant": { ... }
}

• Expiry: 24 hours
• Invalidated on logout (DELETE /v1/auth/logout)
• Not suitable for long-lived server integrations

Environment Modes

API keys carry an environment (sandbox or live). The sandbox processes real transactions against provider test infrastructure with no money movement. Live mode returns 403 Forbidden in this portfolio instance.

{ "error": { "code": "live_mode_disabled", "message": "Live mode is not activated" } }

Rate Limits

Rate-limited requests receive 429 Too Many Requests with a Retry-After header.