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

# Authentication

> How an integration connects to MoonUP, and what a key can reach.

A key is created in the seller dashboard under **Seller → API keys**. It is
shown once, and it acts on behalf of the account until it is revoked.

## Sending the key

The key goes on every request. There are no intermediate tokens to exchange it
for.

```http theme={null}
GET /v1/offers/my HTTP/1.1
Host: api.moonup.gg
Authorization: Bearer moonup_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```bash theme={null}
curl -H "Authorization: Bearer $MOONUP_API_KEY" https://api.moonup.gg/v1/offers/my
```

HTTPS only. A key that has travelled over plain HTTP should be treated as
leaked and rotated.

## What a key reaches

The seller's own offers: list them (`GET /v1/offers/my`), create, edit, manage
units, pause and archive. Anything the dashboard guards with a second factor —
changing the account email, 2FA settings, withdrawals — is out of reach for a
key.

## Address allowlist

Optional. If your integration runs from fixed addresses, list them when you
create the key (an address or a subnet, up to 16 entries) and the key is
refused from anywhere else. An empty list means any address.

## Rate limits

| Budget              | Limit                     |
| ------------------- | ------------------------- |
| Reads               | 500 requests per minute   |
| Writes              | 250 requests per minute   |
| Writes to one offer | 5 per minute, 10 per hour |

Going over returns `429`. It is a temporary refusal: wait and retry, the key
stays valid.

## Rotating a key

An account holds up to 5 keys. Create the replacement before you need it: point
your integration at the new key, confirm it works, then revoke the old one.
Nothing has to go down in between.

## Errors

| Code               | What it means                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `401 unauthorized` | The key is unknown, revoked, or the request came from an address outside the allowlist. Which check failed is not disclosed |
| `403 forbidden`    | The key is valid, but the account may not do this — it lacks the permission, or it is suspended (`account_suspended`)       |
| `429 rate_limited` | One of the budgets above was exceeded                                                                                       |