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.
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"'"
}'
{
"client_id": "your_client_id",
"password": "your_password"
}
{ "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 '{ ... }'
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/usersPOST /v1/users/{id}/verificationsPOST /v1/recipientsPOST /v1/virtual-accountsPOST /v1/virtual-accounts/{id}/payoutPOST /v1/virtual-accounts/{id}/liquidation-address
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.
