> ## Documentation Index > Fetch the complete documentation index at: https://docs.kori.ml/llms.txt > Use this file to discover all available pages before exploring further. # Generate a scoped Bearer token > Exchange your API key (`X-API-Key`) and secret (`X-API-Secret`) for a JWT Bearer token. Optionally restrict the token to a subset of `scopes` (defaults to `["pay","deposit","balance"]`) and set an expiry between 1 and 720 hours (default 24). Rate limited to 20 requests / 15 minutes. ## OpenAPI ````yaml /openapi.yaml post /merchant/api/auth openapi: 3.1.0 info: title: Kori Merchant API version: 1.0.0 description: > The Kori Merchant API lets your application collect and disburse mobile-money payments across Mali (Orange Money, Wave, Sama, Moov) and manage payouts, beneficiaries, bulk payments, payment links, your team, webhooks and settings. Every endpoint documented here is reachable with a **merchant API key**. You exchange your API key + secret for a short-lived **Bearer token** scoped to a set of permissions, then call the rest of the API with that token. The scopes you can grant are exactly the ones shown in the **API Keys** screen of your Kori dashboard. ## Authentication flow 1. `POST /merchant/api/auth` with `X-API-Key` and `X-API-Secret` headers. Optionally request a subset of `scopes` and an expiry (`expires_in_hours`, 1–720). 2. Use the returned `data.token` as `Authorization: Bearer ` on every other call. 3. Each endpoint requires a specific scope; a token missing that scope gets `403`. ## Response envelope All responses share the shape `{ "success": boolean, "message"?: string, "request_id"?: string, "data"?: object }`. Errors set `success: false` and a human-readable `message`. ## Asynchronous payments `POST /merchant/api/pay` returns `202` with `status: "pending"` — the customer has only been *prompted*. Wait for the `payment_received` webhook (or poll the transaction) before treating a collection as paid. Never rely on the HTTP response alone to mark an order complete. contact: name: Kori Support url: https://kori.ml servers: - url: https://api.kori.ml description: Production - url: https://dev.kori.ml description: Sandbox / development security: - BearerAuth: [] tags: - name: Authentication description: Exchange your API key + secret for a scoped Bearer token. - name: Payments description: >- Collect from customers (`pay`), disburse (`deposit`), check balance and transactions. - name: Payouts description: Withdraw your balance to mobile money or bank accounts. - name: Beneficiaries description: Saved payout recipients. - name: Payment Links description: Shareable hosted payment pages. - name: Bulk Pay description: Batch disbursements to many recipients. - name: Team description: Manage dashboard team members and roles. - name: Webhooks description: Register endpoints to receive event notifications. - name: Settings description: Merchant account preferences. paths: /merchant/api/auth: post: tags: - Authentication summary: Generate a scoped Bearer token description: > Exchange your API key (`X-API-Key`) and secret (`X-API-Secret`) for a JWT Bearer token. Optionally restrict the token to a subset of `scopes` (defaults to `["pay","deposit","balance"]`) and set an expiry between 1 and 720 hours (default 24). Rate limited to 20 requests / 15 minutes. requestBody: required: false content: application/json: schema: type: object properties: scopes: type: array items: $ref: '#/components/schemas/Scope' description: Subset of your key's scopes to embed in the token. example: - pay - balance expires_in_hours: type: integer minimum: 1 maximum: 720 default: 24 example: 24 responses: '200': description: Token issued. content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Authentication successful request_id: type: string format: uuid data: type: object properties: token: type: string description: JWT Bearer token token_type: type: string example: Bearer scopes: type: array items: $ref: '#/components/schemas/Scope' expires_in: type: integer description: Seconds until expiry example: 86400 expires_at: type: string format: date-time merchant: type: object properties: id: type: integer business_name: type: string '400': $ref: '#/components/responses/BadRequest' '401': description: Missing/invalid API key or secret. content: application/json: schema: $ref: '#/components/schemas/Error' '403': $ref: '#/components/responses/InactiveMerchant' security: - ApiKeyAuth: [] ApiSecretAuth: [] components: schemas: Scope: type: string description: >- A permission an API-key token can carry. These are the scopes shown in the dashboard's API Keys screen. enum: - pay - deposit - balance - payout - beneficiaries - bulk_pay - payment_links - team - webhooks - settings Error: type: object properties: success: type: boolean example: false message: type: string example: Invalid or missing parameter request_id: type: string format: uuid responses: BadRequest: description: Validation error. content: application/json: schema: $ref: '#/components/schemas/Error' InactiveMerchant: description: Merchant account is inactive. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Scoped Bearer token from `POST /merchant/api/auth`. ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Your merchant API key (`mk_...`). ApiSecretAuth: type: apiKey in: header name: X-API-Secret description: Your merchant API secret (`ms_...`). Used only on `/auth`. ````