Authentication

API keys for integrations, account tokens for the apps, and which endpoints need which.

The API has three kinds of endpoint, and each reference page says which it is.

Kind	How to authenticate	Used for
Partner (API key)	`Authorization: Bearer apk_test_… / apk_live_…`	Everything a business integration does: payouts, recipients, transactions, events, webhooks.
Public	Nothing	Coverage, published fees, fee quotes. Safe to call from anywhere.
Account	`Authorization: Bearer <access token>`	The AutoPayKe app's own endpoints for a signed-in person: top-ups, payment links, live status.

API keys

Create keys in the Console. A request is accepted when the key exists, isn't revoked, expired, suspended, waiting for approval or rejected; comes from an allowed IP; has the scope the endpoint needs; and the workspace isn't suspended. Each failure has its own code, so you can tell them apart. See API keys and Errors.

curl "https://api.autopayke.com/api/v1/account" -H "Authorization: Bearer $AUTOPAYKE_API_KEY"

Account tokens

The account API signs a person in with a one-time code sent to their phone, and returns a short-lived access token and a refresh token. It exists for the AutoPayKe apps and for building on behalf of a person who signs in; it's not how a business integrates payouts. See the existing Requests and responses page and the account endpoints in the API reference.

Account tokens in detail

Two kinds of endpoint

Kind	Header	Examples
Public	None	`/capabilities`, `/fees/*`, `/p/{code}`
Account	`Authorization: Bearer <accessToken>`	`/balance`, `/funding/*`, `/payment-requests`

Account endpoints act on behalf of one AutoPayKe account, with exactly the permissions its owner has in the app. The token is the same one the app uses after sign-in.

Get a token

Signing in is two calls: ask for a one-time code, then exchange it for tokens.

Request a code

The code goes to the account's email, or by SMS when there's no email on file. It's valid for 5 minutes.

curl -X POST "https://api.autopayke.com/api/auth/send-otp" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+254712345678" }'

2
Exchange it for tokens
```
curl -X POST "https://api.autopayke.com/api/auth/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+254712345678", "code": "123456" }'
```
If the account has two-factor sign-in on, the answer is { twoFactorRequired: true, challengeToken } instead. Send the challenge and a code from the authenticator app to POST /api/auth/verify-2fa to get the tokens.

Call an account endpoint

curl "https://api.autopayke.com/api/v1/balance" \
  -H "Authorization: Bearer $AUTOPAYKE_TOKEN"

Token lifetimes

Token	Lasts	Use
`accessToken`	15 minutes	The Authorization header on every account call
`refreshToken`	30 days	Get a new access token: `POST /api/auth/refresh` with `{ refreshToken }`

When a call answers 401 AUTH_ERROR, refresh once and retry. If refreshing fails too, the person must sign in again. POST /api/auth/logout with the refresh token ends the session everywhere it's used.

Keep tokens on your server. A token can move the account's money. Never put one in a mobile app bundle, a web page or a repository. Store refresh tokens encrypted.

Server-to-server access

Tokens belong to a person who signed in. If your integration needs to run without anyone signing in (paying out to many people from your platform, for example) talk to us about partner access.