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

# Authentication

> Authenticate every request with an X-API-Key header. Keys are scoped, shown once at creation, and permanently revocable.

Send your API key in the `X-API-Key` header on every request.

```bash theme={null}
curl -sS "https://api.moove.xyz/v1/payment-link" \
  -H "X-API-Key: mk_live_..."
```

## Get a key

Keys are created in the Moove Dashboard at [moove.xyz/dashboard/api-keys](https://www.moove.xyz/dashboard/api-keys).

<Warning>
  The plaintext key is shown **once**, at creation. It is not stored and cannot be shown again. Copy it into your secret manager immediately.
</Warning>

There is no endpoint that mints a key. Key management is session-authenticated only — a key can never issue another key, so a compromised key cannot escalate itself.

[Moove API Keys →](/manage/moove-api-keys)

## Scopes

A key is issued with explicit scopes. A request is rejected with `403` if the key lacks the scope its operation requires.

| Scope                 | Grants                 |
| --------------------- | ---------------------- |
| `payment_link:create` | Creating payment links |
| `payment_link:read`   | Listing payment links  |

You do not select raw scopes. You select an **agent**, which expands to the scopes it needs.

| Agent                   | Status      | Scopes                                     |
| ----------------------- | ----------- | ------------------------------------------ |
| **Moove Receive Agent** | Live        | `payment_link:create`, `payment_link:read` |
| Moove Send Agent        | Coming soon | —                                          |
| Moove Swap Agent        | Coming soon | —                                          |
| Moove Ramp Agent        | Coming soon | —                                          |

## A key is a down-scope of its owner

<Note>
  A key acts as the user who issued it and can only do a subset of what they can do.

  No endpoint moves funds. Payment links always settle to the key owner's own default wallet, and the caller cannot specify a destination — so a leaked key can create requests that pay its owner, and nothing else.
</Note>

## Handling keys

<Warning>
  * Store keys in a secret manager or environment variable. Never in source control.
  * Never paste a key into a prompt, chat, issue or screenshot.
  * Use one key per service, so revoking one does not take down the rest.
  * Revoke any key you are unsure about and issue a new one.
</Warning>

## Revocation

Revoking a key stops it working immediately.

<Warning>
  **Revocation is permanent.** There is no un-revoke. The plaintext was never stored, so a revoked key could not be used again even if the record were restored.
</Warning>

## Failure modes

| Status | Meaning                                       | What to do                                                            |
| ------ | --------------------------------------------- | --------------------------------------------------------------------- |
| `401`  | Missing, invalid or expired key               | Check the header name and the key value. Do not retry.                |
| `403`  | Key lacks the required scope                  | Issue a key with the right agent. Do not retry.                       |
| `409`  | The account is not set up to receive payments | The owner must claim a handle and set a default wallet. Do not retry. |

[Errors →](/api-reference/errors)

## Next

<CardGroup cols={3}>
  <Card title="Moove Payment Links" icon="link" href="/api-reference/moove-receive/moove-payment-links">
    Make your first call.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/api-reference/errors">
    Every status code.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/rate-limits">
    Per key and per IP.
  </Card>
</CardGroup>