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

# Authentication

> Create an API key and authenticate your requests.

Every request to `/b2b/*` and `/retailer/v1/*` is authenticated with an API key in the `X-API-Key` header.

```bash theme={null}
curl https://api.wizzgift.com/b2b/account \
  -H "X-API-Key: wg_live_..."
```

A missing or invalid key returns `401 UNAUTHORIZED`. A suspended account returns `403` on every call.

## Create an API key

<Steps>
  <Step title="Sign in to the dashboard">
    Create a Wizzgift account at [wizzgift.com](https://www.wizzgift.com) and sign in.
  </Step>

  <Step title="Create a key">
    Go to **Account → API Keys** and create a key. Creating your first key
    automatically enrolls you as a **starter-tier** business with the **b2b**
    capability enabled — no separate signup step.
  </Step>

  <Step title="Store the key immediately">
    The key looks like `wg_live_...` and is shown **exactly once**. Only a
    hash is stored server-side; a lost key must be replaced.
  </Step>
</Steps>

<Warning>
  Treat API keys like passwords. Keep them in your server-side environment, never in client-side code, and rotate them from the dashboard if they leak.
</Warning>

## Key scopes

Each key carries a list of scopes. Operations in the [API reference](/api-reference/introduction) state the scope they require. A key without the needed scope gets `403 FORBIDDEN`.

Pick the scopes when you create the key — the dialog lists all of them, with every scope selected by default. Scopes are fixed once the key exists; to change them, create a replacement key and delete the old one.

| Scope             | Grants                                              |
| ----------------- | --------------------------------------------------- |
| `orders:create`   | Create orders, checkouts, and payment invoices      |
| `orders:read`     | Read orders and checkouts; manage webhook endpoints |
| `balance:read`    | Read balance and account overview                   |
| `products:read`   | Read the catalog and payment methods                |
| `refunds:create`  | Request refunds                                     |
| `refunds:read`    | Read refund status                                  |
| `deposits:create` | Create balance top-ups                              |
| `deposits:read`   | Read deposit status and history                     |

Grant only what the integration needs — a reporting job wants just `products:read` and `orders:read`, not the create scopes.

A key with the `*` scope has full access; keys created before scopes existed also carry full access and keep working. Any scope outside the table above is rejected at creation with `400 VALIDATION_ERROR`.

## Account capabilities

Scopes control what a *key* may do; capabilities control which *surfaces* your account can use:

* **b2b** — enabled automatically when you create your first API key.
* **retailer** — enable it in the dashboard business settings, or contact support.

Calling a surface whose capability is off returns `403 FORBIDDEN` with a hint in the error message.

## Account status

Your account status is visible on [`GET /b2b/account`](/api-reference/introduction):

| Status           | Effect                                                  |
| ---------------- | ------------------------------------------------------- |
| `active`         | Normal operation                                        |
| `under_review`   | Advisory — the API keeps working                        |
| `info_requested` | Advisory — check `statusNote` for what we need from you |
| `suspended`      | All API access blocked (`403`)                          |