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

# Authentication

> Authenticate requests to the MW Payouts API with a Bearer API key.

The MW Payouts API authenticates every request with an API key passed as a Bearer token. Keys are created and managed in the dashboard.

## Create an API key

<Steps>
  <Step title="Open the Developers section">
    Go to [business.madhousewallet.com/developers](https://business.madhousewallet.com/developers).
  </Step>

  <Step title="Create a key">
    Select **Create API Key**, give it a descriptive name (for example, `Production server`), and confirm. You can have up to 5 keys at a time.
  </Step>

  <Step title="Copy and store it">
    The full key is shown **once**. Copy it immediately and store it in a secrets manager or environment variable. If you lose it, revoke the key and create a new one.
  </Step>
</Steps>

## Key format

A key has the following shape:

```text theme={null}
mw_live_<keyId>_<secret>
```

* `keyId` — an 8-character non-secret prefix used to identify the key in the dashboard.
* `secret` — a 32-character high-entropy secret.

Only a hash of the full key is stored, so the plaintext value cannot be recovered after creation.

## Authenticate a request

Pass the key in the `Authorization` header as a Bearer token.

```bash theme={null}
curl "https://business.madhousewallet.com/api/payouts/fee?amount=100" \
  -H "Authorization: Bearer mw_live_<keyId>_<secret>"
```

<Warning>
  API keys are for **server-side use only**. Anyone with your key can move funds on your behalf. Never expose a key in browser code, mobile apps, or public repositories.
</Warning>

## IP restriction

You can restrict each account's API keys to a single IPv4 address from the **Developers** section. When enabled, any request from a different address is rejected with `403`. Enter the public IPv4 address of your server, and leave it blank to disable the restriction.

## Revoke a key

Revoke a key from the dashboard at any time. Any server still using a revoked key loses access immediately, so roll keys by creating the replacement first and updating your environment before revoking the old one.

## Errors

A missing, malformed, or revoked key returns `401`. A key used from a disallowed IP returns `403`. See [Rate limits and errors](/rate-limits-and-errors) for the full error model.