Authentication

The Paygasus Pay API authenticates every request with a secret key sent as a bearer token.

curl https://api.paygasus.com/payments/card \
  -H "Authorization: Bearer sk_test_…"

A request without a valid key is rejected before any processing happens.

If your HTTP client makes bearer tokens awkward, HTTP Basic works too — send the key as the username and leave the password empty:

curl https://api.paygasus.com/payments/card -u "sk_test_…:"

Both forms are equivalent. Only /healthz is reachable without a key.

Live vs. test keys

Your key’s prefix selects the environment:

Prefix	Mode	Effect
sk_live_…	Live	Moves real money. Responses have "livemode": true.
sk_test_…	Test	No money moves. Responses have "livemode": false.

The two are otherwise identical: same endpoints, same object shapes. Build and test against sk_test_, then swap the key to go live. See Test mode for simulating specific outcomes.

Keep secret keys secret

A secret key can create and move payments. Never embed it in client-side code, mobile apps, or a public repository. Keep it server-side and inject it from a secrets manager or environment variable.

What a key scopes you to

A key resolves to exactly one merchant and one mode, and that resolution is applied at the data layer. So a key can only ever see its own merchant’s data, in its own mode.

Both boundaries return 404, never 403. Asking for an intent that belongs to another merchant, or a live intent with a test key, is answered as though the resource does not exist.

Authentication errors

All authentication failures return 401 with the same message; branch on code.

401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The provided API key is invalid."
  }
}

code	Meaning
api_key_missing	No Authorization header was sent.
api_key_invalid	Malformed key, or no such key.
api_key_revoked	The key existed and has been revoked.

You may also see 422 unprocessable on card endpoints if your merchant account has no processor configuration for the mode you’re using. That’s a setup gap, not a credential problem. Contact support.

Test and live are provisioned separately and completely: a working test-mode key does not imply your live mode is ready, and a live charge will return 422 until it is. Nothing falls back from one mode to the other, so there is no configuration state in which a live charge is quietly processed with test-mode settings.

Managing keys

Secret keys are created, rotated, and revoked in the Paygasus dashboard. There is no key-management endpoint in this API.

A new key’s full value is shown once, at creation. It is stored only as a hash, so it cannot be recovered or re-displayed afterwards. Copy it into your secrets manager immediately. If you lose it, create a new key and revoke the old one.

Revocation is immediate and permanent: the next request with that key returns 401 api_key_revoked. There is no propagation delay to wait out and a revoked key cannot be reactivated. Rotate immediately if a key is ever exposed.