Authentication
API keys, request headers and network scopes for the proposed API.
Bearer token
In this proposed contract, each integration receives a secret API key scoped to its allowed networks. All endpoints require it in the authorization header. Example keys are placeholders, not issued credentials.
Authorization: Bearer YOUR_MOKUNA_API_KEYKeep credentials server-side
Store the key in your backend environment or secret manager. A public browser bundle, mobile app or Telegram message is not an appropriate place for a shared secret. Route API requests through a trusted application service.
export MOKUNA_API_KEY="YOUR_MOKUNA_API_KEY"
export MOKUNA_API_BASE="https://api.mokuna.xyz/v1"Request headers
| Header | Required | Purpose |
|---|---|---|
Authorization | All requests | Bearer token for the integration. |
Content-Type | POST requests | Set to application/json. |
Idempotency-Key | POST /transactions | Stable key for one logical submission; reuse it only for retries of the same body. |
Scope & authentication errors
A missing or invalid token returns 401. A recognized token without access to the requested network returns 403. Resolve authentication or scope issues before retrying; backoff alone will not fix them.
Rotation workflow
For the planned workflow, provision a replacement key, update the application secret, validate the new key and retire the previous key after in-flight work is accounted for. Provisioning and revocation are handled with the team in this design; no key-management endpoint is defined here.