> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waftpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Authentication Token

> Exchange your consumer credentials for a short-lived Bearer token.

## Overview

Use this endpoint to exchange your **consumer\_key** and **consumer\_secret** for a short-lived Bearer token. This is a server-to-server flow and does **not** require an existing Bearer token.

<Info>
  Use this token when calling protected Waftpay APIs such as Collections, Payouts, Remittance, Checkout, Wallet Balance, and Transaction Status Query.
</Info>

***

## Environments

| Environment | Base URL                 |
| ----------- | ------------------------ |
| Sandbox     | `https://dev.waftpay.io` |
| Production  | `https://waftpay.io`     |

<Warning>
  Sandbox and Production credentials are separate. Use Sandbox credentials on `https://dev.waftpay.io` and Production credentials on `https://waftpay.io`.
</Warning>

***

## Endpoint

```http theme={null}
POST /auth/api/v1/generate-token
```

***

## Full URLs

| Environment | URL                                                 |
| ----------- | --------------------------------------------------- |
| Sandbox     | `https://dev.waftpay.io/auth/api/v1/generate-token` |
| Production  | `https://waftpay.io/auth/api/v1/generate-token`     |

***

## Request body

```json theme={null}
{
  "consumer_key": "APP_CONSUMER_KEY",
  "consumer_secret": "APP_CONSUMER_SECRET"
}
```

| Field             | Type   | Required | Description                            |
| ----------------- | ------ | -------- | -------------------------------------- |
| `consumer_key`    | string | Yes      | Your product-specific consumer key.    |
| `consumer_secret` | string | Yes      | Your product-specific consumer secret. |

***

## Example request

<Tabs>
  <Tab title="Sandbox">
    ```bash theme={null}
    curl --request POST \
      --url https://dev.waftpay.io/auth/api/v1/generate-token \
      --header 'Content-Type: application/json' \
      --data '{
        "consumer_key": "APP_CONSUMER_KEY",
        "consumer_secret": "APP_CONSUMER_SECRET"
      }'
    ```
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    curl --request POST \
      --url https://waftpay.io/auth/api/v1/generate-token \
      --header 'Content-Type: application/json' \
      --data '{
        "consumer_key": "APP_CONSUMER_KEY",
        "consumer_secret": "APP_CONSUMER_SECRET"
      }'
    ```
  </Tab>
</Tabs>

***

## Example response (success)

```json theme={null}
{
  "status": true,
  "message": "Request processed successfully",
  "token": "abcdeFGHIjklmno@1234567890...",
  "expires_in": 3600
}
```

***

## Response fields

| Field        | Type    | Description                                         |
| ------------ | ------- | --------------------------------------------------- |
| `status`     | boolean | Indicates whether the token request was successful. |
| `message`    | string  | Human-readable response message.                    |
| `token`      | string  | Bearer token to use on protected API requests.      |
| `expires_in` | number  | Token validity duration in milliseconds.            |

***

## Using the token

Use the token in the `Authorization` header:

```http theme={null}
Authorization: Bearer <token>
```

Example:

```bash theme={null}
curl --request GET \
  --url https://dev.waftpay.io/tsq/api/v1/wallet-balances \
  --header 'Authorization: Bearer <token>'
```

***

## Token lifecycle

<Steps>
  <Step title="Generate token">
    Call this endpoint using your product-specific consumer credentials.
  </Step>

  <Step title="Cache token securely">
    Store the token server-side and reuse it for subsequent API requests until it expires.
  </Step>

  <Step title="Refresh on expiry">
    Generate a new token only when the current token expires or becomes invalid.
  </Step>
</Steps>

***

## Notes

* Use the credentials for the **specific product** you are calling: Payouts, Collections, Remittance, Checkout, Wallet Balance, or Transaction Status Query.
* This endpoint does **not** require Bearer authentication.
* Never expose your `consumer_secret` in frontend or mobile applications.
* If you regenerate your keys, the old credentials stop working immediately.


## OpenAPI

````yaml POST /auth/api/v1/generate-token
openapi: 3.1.0
info:
  title: Waftpay Payments API
  description: >-
    Process payments, collect funds, and remit payouts with Waftpay. Includes
    Authentication Token, idempotency, webhooks, and sandbox support.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://dev.waftpay.io
    description: Sandbox (dev)
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Obtain and manage access tokens
  - name: Payments
    description: Charge a customer and track status
  - name: Collections
    description: Customer-initiated payments and hosted checkouts
  - name: Checkout
    description: >-
      Hosted checkout flow for customer payments.


      Flow:

      1. Ensure the Collections service is enabled for your account.

      2. Use `consumer_key` and `consumer_secret` to generate a Bearer token via
      **Get Authentication Token**.

      3. Cache the token and refresh only on expiry.

      4. Call **Create Checkout Request** with customer details, amount, and
      redirect URLs.

      5. Use the returned `checkout_url` for redirect or iframe.

      6. The `callback_url` receives a payload matching the `CheckoutCallback`
      schema.
  - name: Remittance
    description: Send payouts to mobile wallets and bank accounts
  - name: Webhooks
    description: Receive asynchronous notifications
  - name: Utilities
    description: Common utilities (idempotency, health)
paths:
  /auth/api/v1/generate-token:
    post:
      tags:
        - Authentication
      summary: Get Authentication token
      description: >-
        Exchange **consumer_key** and **consumer_secret** for a short-lived
        **Bearer** token.
      operationId: auth-token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - consumer_key
                - consumer_secret
              properties:
                consumer_secret:
                  type: string
                consumer_key:
                  type: string
                  format: password
            examples:
              clientCredentials:
                value:
                  consumer_key: APP_CONSUMER_KEY
                  consumer_secret: APP_CONSUMER_SECRET
      responses:
        '201':
          description: Authentication token generated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - token
                  - expires_in
                properties:
                  status:
                    type: boolean
                    example: true
                    description: Indicates if the request was successful
                  message:
                    type: string
                    example: Request processed successfully
                  token:
                    type: string
                    description: JWT bearer token to use in Authorization header
                  expires_in:
                    type: integer
                    description: Token validity in milliseconds
                    example: 3600
              examples:
                ok:
                  value:
                    status: true
                    message: Request processed successfully
                    token: abcdeFGHIjklmno@1234567890...
                    expires_in: 3600
        '400':
          description: Invalid consumer key or secret
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - token
                  - expires_in
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Invalid consumer key or secret
                  token:
                    type: string
                    example: ''
                  expires_in:
                    type: integer
                    example: 0
              examples:
                invalidCredentials:
                  value:
                    status: false
                    message: Invalid consumer key or secret
                    token: ''
                    expires_in: 0
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````