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

# Managing API Keys for Your Merchant Account

> Generate, inspect, and revoke API keys to authenticate your IteraPay integration. Each merchant account has one active key at a time.

API keys are how your application authenticates with the IteraPay API. Every request you make on behalf of your merchant account must include an active API key in the `Authorization` header. This page walks you through generating a key, checking its status, and revoking it when needed.

<Info>
  API keys are scoped to a single merchant. Each merchant account can have only one active API key at a time. If you generate a new key, the previous key is immediately invalidated.
</Info>

## Generating an API key

To start accepting payments, you need to generate an API key for your merchant account. You must authenticate this request with your Bearer token (JWT), which you receive when you log in.

<Steps>
  <Step title="Authenticate with your Bearer token">
    Make sure you have a valid JWT from your IteraPay login session. You'll include this in the `Authorization` header as `Bearer <your-jwt>`.
  </Step>

  <Step title="Call the generate endpoint">
    Send a `POST` request to `/key/generate/{merchantID}`, replacing `{merchantID}` with your merchant ID.

    ```bash generate-api-key.sh theme={null}
    curl --request POST \
      --url https://api.iterapay.com/key/generate/YOUR_MERCHANT_ID \
      --header 'Authorization: Bearer YOUR_JWT_TOKEN'
    ```
  </Step>

  <Step title="Store the returned key securely">
    The response contains your API key value. Copy it immediately and store it in a secure secrets manager or environment variable — IteraPay does not display the full key again after this point.

    ```json response theme={null}
    {
      "apiKey": "ipa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
    ```
  </Step>
</Steps>

<Warning>
  Generating a new API key **immediately revokes** the previous key. Any running integrations using the old key will begin receiving authentication errors. Rotate keys during a maintenance window or update your application before generating a replacement.
</Warning>

## Viewing key information

You can retrieve metadata about your current API key — such as when it was created and when it was last used — without exposing the key value itself. Use this to audit key activity or verify a key exists.

```bash get-key-info.sh theme={null}
curl --request GET \
  --url https://api.iterapay.com/key/info/YOUR_MERCHANT_ID \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
```

The response includes fields like `createdAt` and `lastUsedAt`:

```json response theme={null}
{
  "createdAt": "2026-03-15T10:22:00Z",
  "lastUsedAt": "2026-05-07T18:45:12Z"
}
```

If you notice a `lastUsedAt` timestamp from a time when you didn't make any requests, your key may be compromised. Revoke it immediately and generate a new one.

## Using your API key in requests

Once you have an API key, include it in the `X-Api-Key` header on every API request:

```bash authenticated-request.sh theme={null}
curl --request GET \
  --url https://api.iterapay.com/merchants/YOUR_MERCHANT_ID/invoices \
  --header 'X-Api-Key: ipa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
```

<Tip>
  Store your API key in an environment variable (e.g., `ITERAPAY_API_KEY`) rather than hardcoding it in your application. This makes key rotation easier and avoids accidental exposure in version control.
</Tip>

## Revoking an API key

Revoke your API key when you suspect it has been compromised, when offboarding a system that uses it, or as part of a planned key rotation. Once revoked, all requests using that key will fail until you generate a new one.

```bash revoke-api-key.sh theme={null}
curl --request DELETE \
  --url https://api.iterapay.com/key/revoke/YOUR_MERCHANT_ID \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
```

A successful revocation returns `204 No Content` with an empty response body. After revoking, you can immediately generate a new key using the generate endpoint described above.

## Request and response reference

### `POST /key/generate/{merchantID}`

<ParamField path="merchantID" type="string" required>
  Your unique merchant identifier.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer JWT token from your login session. Format: `Bearer <token>`.
</ParamField>

**Response**

<ResponseField name="apiKey" type="string" required>
  The newly generated API key. Store this value securely — it is not retrievable after this response.
</ResponseField>

***

### `GET /key/info/{merchantID}`

<ParamField path="merchantID" type="string" required>
  Your unique merchant identifier.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer JWT token. Format: `Bearer <token>`.
</ParamField>

**Response**

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the current key was generated.
</ResponseField>

<ResponseField name="lastUsedAt" type="string">
  ISO 8601 timestamp of the most recent authenticated request using this key.
</ResponseField>

***

### `DELETE /key/revoke/{merchantID}`

<ParamField path="merchantID" type="string" required>
  Your unique merchant identifier.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer JWT token. Format: `Bearer <token>`.
</ParamField>

Returns `204 No Content` on success.