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

# Authentication

> Get an API key, send it with every request, and keep it safe.

Every API endpoint needs an API key. Send it in the `x-api-key` header.

## Get an API key

1. Log in to the [Dashboard](https://business.afriex.com/).
2. Go to **Developer** and open the **API Keys** tab.
3. Generate a key, choose its [permissions](/api-reference/permissions), and store it securely.

The dashboard has a **Test / Live** toggle. Keys you create in test mode work against the sandbox, and keys you create in live mode work against production. Each mode has its own keys.

## Send the key

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  https://sandbox.api.afriex.com/api/v1/customer
```

Use the base URL that matches your key:

| Environment | Base URL | Keys from |
| - | - | - |
| Sandbox | `https://sandbox.api.afriex.com` | Test mode |
| Production | `https://api.afriex.com` | Live mode |

<Warning>
  Never use a production API key in your testing environment.
</Warning>

## Permissions

A business can have several API keys, and each key has its own set of [permissions](/api-reference/permissions), such as reading transactions or creating deposits. You choose the permissions when you create a key. To remove a key's access, delete the key. Manage your keys under **Developer → API keys** in the dashboard.

* A key that is missing the permission an endpoint needs is rejected with `401 Unauthorized`.
* An unrecognised, malformed, or revoked key returns `401 Unauthorized` as well.

<Note>
  These two cases look the same on purpose. If a request that used to work starts returning `401`, check the key's permissions in the dashboard before you assume the key itself is bad.
</Note>

See [Permissions](/api-reference/permissions) for the permission each endpoint requires.

## IP allowlist

One allowlist covers every API key in your business. Once you add an address, the API accepts requests only from the addresses on your list. See [IP allowlisting](/api-reference/ip-allowlisting).

## Request signing

Some businesses have payload signing enabled. When it is, send the request signature in the optional `x-api-signature` header:

```
x-api-signature: your-request-signature
```

If signing is not enabled for your business, this header is not required. Contact [support@afriex.com](mailto:support@afriex.com) to enable it.

## Protecting your keys

* Keep API keys on your server. Never put one in a mobile app, a browser, or a public repository.
* Use sandbox keys against the sandbox and production keys against production.
* Give each key only the permissions it needs. If a key may be exposed, [rotate it](#rotate-a-key) straight away.
* Restrict API access to your servers with an [IP allowlist](/api-reference/ip-allowlisting).

## Rotate a key

Rotate a key on a schedule, when someone with access to it leaves, or straight away if it may have been exposed. A business can hold several keys at once, so you can switch with no downtime:

<Steps>
  <Step title="Create the new key">
    In the dashboard, go to **Developer → API keys**, click **Create new keys**, give the key the same [permissions](/api-reference/permissions) as the old one, and click **Generate key**. Copy it into your secret store.
  </Step>

  <Step title="Deploy it">
    Point every server that calls the API at the new key, and deploy.
  </Step>

  <Step title="Check that nothing still uses the old key">
    Confirm your requests succeed with the new key and that nothing in your logs still sends the old one.
  </Step>

  <Step title="Revoke the old key">
    Click **Revoke** on the old key and confirm. Revoking takes effect at once and can't be undone, and any request that still sends the old key gets `401`.
  </Step>
</Steps>

If a key was exposed, don't wait for a deploy window. Revoke it as soon as the new key is live, and accept a few failed requests over leaving the old key usable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.