Authentication and API keys

You authenticate API requests with a secret key. Send it as a bearer token in the Authorization header.

curl https://api.abuna.app/v1/apps/01J9ZQ4Y7R3T6V8W2X5B1C0DEF/products \
  -H "Authorization: Bearer sk_test_..."

The API also reads the key from an X-Api-Key header. It checks that header only when Authorization doesn't hold a bearer token.

curl https://api.abuna.app/v1/apps/01J9ZQ4Y7R3T6V8W2X5B1C0DEF/products \
  -H "X-Api-Key: sk_test_..."

Secret keys

A secret key is sk_test_ or sk_live_ followed by 48 hex characters. Each key belongs to one app ID in one mode. The app ID in the path must match the key's app, so a Test key can't reach Live data.

Abuna shows your first Test key and Live key once, when you create the app. To add a key, open Settings, then API keys. An app can have several active keys, so you can switch to a new key before you revoke the old one. Only team owners can create or revoke keys.

What a secret key can do

A secret key works on every /v1/apps/{appID}/... endpoint for its app, with these exceptions. They need a dashboard sign-in, so a leaked key can't take over your app:

• Changing app settings, including the webhook URL
• Listing, creating, or revoking API keys
• Rotating the publishable key or the webhook signing secret
• Connecting, viewing, or disconnecting a payment provider

A secret key calling one of these gets 403 with code forbidden. You can still read the app with GET /v1/apps/{appID}, which returns its publishable key.

The other way round, sessions take a secret key only. A dashboard sign-in or a publishable key that tries to create, list, read, or expire one gets 403 with code forbidden. That includes each endpoint that creates one, like POST /v1/apps/{appID}/subscriptions/start.

Publishable keys and webhook signing secrets

Each app also has a publishable key and a webhook signing secret. Neither one authenticates API requests.

• The publishable key (pk_test_ or pk_live_) goes in checkout links, as publishkey=pk_test_.... It's safe to show customers. Rotating it breaks every checkout link that holds the old key.
• The webhook signing secret (whsec_test_ or whsec_live_) signs the webhooks Abuna sends you. Keep it on your server. See Receiving webhooks.

Each one is its prefix followed by 48 hex characters.

Failed authentication

• An app ID that doesn't exist returns 404 with code not_found.
• A missing, revoked, or wrong key returns 403 with code forbidden. So does a key for a different app.
• A Live app whose team owner hasn't verified their email returns 403 with code email_unverified.