> For the complete documentation index, see [llms.txt](https://docs.wandreferrals.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wandreferrals.com/integrations-and-api-production-rollout-gate-pending/developer-api-keys.md).

# API keys and scopes

> **Production status:** Public API rollout is not approved, and a universal server-side API kill switch is not yet implemented. The controls below describe the implemented preview surface; use only authorized controlled validation. Do not mint or use a key for a production integration until the production safety gate, review, and separate rollout approval are complete.

## What it does

The **Developer** page is where you mint and manage **scoped API keys** for the public REST API, and it points you to the events and webhooks endpoints your developer will use. Keys are hashed at rest and the full secret is shown **only once**.

## Plan requirement

Creating API keys is a **Professional-plan** feature (**API access**). On lower plans the page shows an upgrade notice with a **View plans** link. Minting, rotating, or revoking a key requires the owner-level **Billing: write** permission.

> **Read vs write.** A Professional key supports the full documented read/write API. Grandfathered Enterprise shops retain the same access with their existing higher rate limit for compatibility; Enterprise is not an upgrade target. See [The public REST API](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/public-api/README.md) for the full plan table.

## Create a key

1. Open **Developer** and click **Create key**.
2. Enter a **Label** (e.g. "Production server").
3. Select the **Scopes** the key should have. Scopes only tighten access — they can't grant more than your plan allows. Available scopes include: `affiliates:read/write`, `commissions:read`, `coupons:read/write`, `payouts:read/write`, `programs:read/write`, `analytics:read`, `events:write`, and `webhooks:read/write`.
4. Click **Generate key** and **copy the secret now** — it won't be shown again (only a hash is stored).

The keys table lists each key's Label, key prefix, Scopes, Created, Last used, and Status. On an active key you can **Rotate** (issues a new secret and revokes the old one) or **Revoke** (stops it immediately). All three actions are audit-logged.

## Using the key

Send it as a Bearer token:

```
Authorization: Bearer <api_key>
```

`POST /api/v1/events` requires an `Idempotency-Key` for money-bearing `conversion` requests. Other mutations use their documented endpoint-specific retry and conflict behavior; do not assume they replay a generic idempotency key. Rate limits and the standard `X-RateLimit-*` response headers are described in the [public API reference](/integrations-and-api-production-rollout-gate-pending/reference.md).

## Server-side conversions — the events API

`POST /api/v1/events` (scope `events:write`) reports events from a headless or non-Shopify checkout. It accepts three types:

* **`conversion`** — a money-bearing event that funnels into the *same* commission engine as a Shopify order. It **requires an `Idempotency-Key` header**; all amounts are integer cents.
* **`click`** and **`page_view`** — non-money tracking events. A successful persisted write returns `202`; a temporary ingestion failure returns `503` and can be retried.

Conversions map their hints to the same attribution evidence buckets (coupon, ref/click, customer, line items) — there is no separate money path. See [How attribution works](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/attribution/how-attribution-works/README.md).

## Outbound webhooks

Subscribe to events with `GET/POST/DELETE /api/v1/webhooks` (scopes `webhooks:read` / `webhooks:write`). The application currently emits `affiliate.approved/rejected/status_changed` and `commission.created`. Other names returned by the subscription registry are reserved filters and do not have lifecycle producers yet. Each delivery is signed with `X-Wand-Signature` (HMAC-SHA256). Full details, the reserved-name list, and verification code are in [Outbound webhooks](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/outbound-webhooks/README.md).

> Webhook subscriptions are managed through the API today — the Developer page itself only manages API keys.

## Related

* [The public REST API](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/public-api/README.md)
* [Outbound webhooks (Zapier, Make & custom)](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/integrations/outbound-webhooks/README.md)
* [Public REST API reference](/integrations-and-api-production-rollout-gate-pending/reference.md)
* [Billing plans](https://github.com/wand-referrals-app/wand-referrals/tree/codex/gitbook-docs-foundation/docs/manual/account/billing-plans/README.md)