Authentication

Every Kira API call is authenticated with two pieces: your x-api-key header and a short-lived bearer token. You obtain the token by calling POST /auth with your client_id and password, then send it as Authorization: Bearer <access_token> on subsequent requests.

Your credentials

Kira provisions three credentials for your account:

Credential	Used for
`client_id`	Identifies your account in the `POST /auth` request body.
`password`	Authenticates the `POST /auth` request body.
`api_key`	Sent as the `x-api-key` header on every request, including `POST /auth`.

Keep these out of source control. Load them from your environment — for example KIRA_CLIENT_ID, KIRA_PASSWORD, and KIRA_API_KEY.

Rotating credentials

There is no self-serve endpoint to rotate your client_id, password, or api_key. Plausible key-management paths (/v1/api-keys, /v1/api-keys/rotate, /v1/keys, /v1/credentials, and similar) all return a 403 with code: "invalid_request" and the message “The request could not be matched to a valid route, or was malformed.” — a routing/request error, not a real endpoint with its own validation. To rotate any of your credentials, contact your assigned Customer Success Manager.

Get an access token

Call POST /auth to exchange your client_id and password for a bearer token. This request carries the x-api-key header but does not require an Authorization header — it is the one endpoint that needs only x-api-key.

curl https://api.balampay.com/sandbox/auth \
  -H "x-api-key: $KIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "'"$KIRA_CLIENT_ID"'",
    "password": "'"$KIRA_PASSWORD"'"
  }'

The request body is just the two credentials:

{
  "client_id": "your_client_id",
  "password": "your_password"
}

A successful response returns the token inside the standard { "message", "data" } envelope:

{
  "message": "...",
  "data": {
    "access_token": "eyJhbGciOi...",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}

Field	Value
`data.access_token`	The bearer token to send on every subsequent call.
`data.expires_in`	`3600` — the token’s lifetime in seconds (1 hour).
`data.token_type`	`Bearer`.

Use the token

Send the token as a bearer token on every other request, alongside your x-api-key header. Both are required together:

curl https://api.balampay.com/sandbox/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $KIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'

Required headers

These headers apply across the API. The Authorization token comes from the POST /auth step above; the rest come from your account configuration.

Header	Value	When
`Authorization`	`Bearer <access_token>`	Every call except `POST /auth`.
`x-api-key`	`<api_key>`	Every call, including `POST /auth`.
`X-Api-Version`	`2026-04-14`	Per request, until you pin your account. Can be dropped once `POST /v1/versioning/upgrade` succeeds — see Versioning.
`Idempotency-Key`	`<UUID v4>`	Required on the write endpoints listed below.

Idempotency-Key is required on:

POST /v1/users
POST /v1/recipients
POST /v1/virtual-accounts
POST /v1/virtual-accounts/{id}/payout

Generate a fresh UUID v4 per request (for example, uuidgen).

Token lifetime

The access token is valid for 3600 seconds (1 hour), as reported by data.expires_in. When it expires, call POST /auth again to obtain a new token. There is no refresh-token flow — re-authenticate with your client_id and password.

Authentication errors

All authentication failures return 401 Unauthorized with a JSON body of the form { "code": "unauthorized", "message": "<reason>" }.

POST /auth rejects the credentials. Verify your client_id and password, and confirm your x-api-key header is set and correct.
A subsequent call is missing or has an invalid bearer token, or the token has expired. Re-run POST /auth to obtain a fresh token, then retry the request. There is no refresh-token flow.

Cache the access token and re-use it until it is close to expiry. Re-authenticate (and retry once) whenever a call returns 401.

For the full list of integration gotchas — status casing, field renames, and other quirks — see Known limitations & quirks.

Getting started

Core concepts

Migrations

Webhooks

Your credentials

Rotating credentials

Get an access token

Use the token

Required headers

Token lifetime

Authentication errors

​Your credentials

​Rotating credentials

​Get an access token

​Use the token

​Required headers

​Token lifetime

​Authentication errors

Your credentials

Rotating credentials

Get an access token

Use the token

Required headers

Token lifetime

Authentication errors