# Authentication (/docs/api-reference/authentication)

## API keys [#api-keys]

Create keys in the Swop web app at **Dashboard → Developer**. Each key has:

| | Format | Notes |
|---|---|---|
| Key ID | `mk_…` | Safe to log and show |
| Secret | `swop_sk_…` | **Shown once at creation.** Swop stores only a hash and can't show it again. |

Keys are server credentials. Keep the secret in an environment variable on your server. Never put it in browser JavaScript, a mobile app or a public repository. If a key leaks, revoke it in the Developer page and create a new one.

## Sending the key [#sending-the-key]

Use either header:

```bash tab="Authorization header"
curl https://apps.apiswop.co/api/v5/merchant/me \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```

```bash tab="X-API-Key header"
curl https://apps.apiswop.co/api/v5/merchant/me \
  -H "X-API-Key: $SWOP_MERCHANT_KEY"
```

## Scopes [#scopes]

A key can do only what its scopes allow. Tick the fewest you need.

| Scope | Lets the key… |
|---|---|
| `profile.read` | Read your public profile |
| `commerce.read` | Read your products, orders and checkouts |
| `commerce.checkout` | Create checkouts from a cart. **The only scope that can lead to money moving.** |
| `commerce.embed` | Mint embed tokens so a registered website can frame your checkout |
| `commerce.card` | Offer card payments. Active only while your account is verified for card. |
| `commerce.write` | Reserved for creating and editing products |
| `drops.read` | Read your locations and terminals |
| `drops.write` | Reserved for editing locations and drops |

### Granted vs. effective scopes [#granted-vs-effective-scopes]

**Granted** scopes are what you ticked. **Effective** scopes are what the key can do **right now**. They differ in one case: `commerce.card` only becomes effective while your account is verified for card. If verification lapses, or can't be checked, the key keeps working for everything else and simply can't offer card. [`GET /me`](/docs/api-reference/me) shows the effective scopes.

## Failures [#failures]

| Status | Meaning |
|---|---|
| `401` | No key, unknown key, or revoked key. Every case returns the same message, so keys can't be probed. |
| `403` | Valid key, missing scope. The body names the scope and lists `grantedScopes` and `effectiveScopes`. |
| `403` with `code: "ACCOUNT_FLAGGED"` | The account is restricted. Contact support. |

```json
{
  "success": false,
  "state": "failed",
  "message": "This key does not have the \"commerce.card\" scope right now.",
  "hint": "Card requires completing merchant verification. Crypto checkout does not.",
  "grantedScopes": ["commerce.read", "commerce.checkout", "commerce.card"],
  "effectiveScopes": ["commerce.read", "commerce.checkout"]
}
```
