# Authentication and API keys (/docs/get-started/authentication)

Merchant API requests go to:

```text
https://apps.apiswop.co/api/v5/merchant
```

Every request carries a **merchant API key**. A key acts as your account, limited to the scopes you gave it.

## Create a key [#create-a-key]

<Steps>
<Step>
Open the Swop web app and go to **Dashboard → Developer**.
</Step>
<Step>
Under **Create an API key**, name the key and tick its scopes.
</Step>
<Step>
Copy the secret. It starts with `swop_sk_` and **is shown once**. If you lose it, revoke the key and create a new one.
</Step>
</Steps>

## Scopes [#scopes]

Give each key only what it needs.

<ParamTable rows={[
  { name: 'commerce.read', type: 'scope', description: 'Read your products, orders and checkouts.' },
  { name: 'commerce.checkout', type: 'scope', description: 'Create checkouts from a cart. The only scope that can lead to money moving.' },
  { name: 'commerce.embed', type: 'scope', description: 'Mint short-lived embed tokens so a website you registered can frame your checkout.' },
  { name: 'commerce.card', type: 'scope', description: 'Take card payments. Only active while your account is verified for card.' },
  { name: 'commerce.write', type: 'scope', description: 'Create and edit products.' },
  { name: 'profile.read', type: 'scope', description: 'Read your public profile.' },
  { name: 'drops.read / drops.write', type: 'scope', description: 'Read or edit your drop locations.' },
]} />

`commerce.card` is checked when each request is made. If you ticked it but your account isn't verified for card yet, the key works for everything else and leaves card out of `effectiveScopes`.

## Send the key [#send-the-key]

Use the `Authorization` header (or `X-API-Key`):

<CodeTabs items={['curl', 'Node', 'Python']}>
<Tab value="curl">
```bash
curl https://apps.apiswop.co/api/v5/merchant/me \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```
</Tab>
<Tab value="Node">
```js
await fetch('https://apps.apiswop.co/api/v5/merchant/me', {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
```
</Tab>
<Tab value="Python">
```python
requests.get(
    "https://apps.apiswop.co/api/v5/merchant/me",
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
)
```
</Tab>
</CodeTabs>

## Keep it on your server [#keep-it-on-your-server]

<Callout type="danger" title="A key in the browser is a public key">
  Never put `swop_sk_…` in HTML, browser JavaScript or a mobile app. Keep it in a server environment variable such as `SWOP_MERCHANT_KEY`, and have your server call Swop.
</Callout>

Some actions can't be done with a key at all. Creating or revoking keys, registering websites that may frame your checkout, and changing webhooks only happen in the Swop app while you're signed in. A leaked key therefore can't lock you out or redirect your webhooks.

## When auth fails [#when-auth-fails]

| Status | Meaning |
|---|---|
| `401` | No key, or the key is invalid or revoked. The message is the same either way, so nobody can probe which keys exist. |
| `403` | The key is valid but lacks the scope this endpoint needs. The body lists `grantedScopes` and `effectiveScopes`. |
| `403` `ACCOUNT_FLAGGED` | The account is restricted. |

More in [Errors](/docs/get-started/errors).

## Other kinds of auth [#other-kinds-of-auth]

- **AI assistants** connect to Swop through the [Swop MCP](/docs/mcp) with OAuth 2.1. People sign in with Swop in a browser; nobody pastes a key into a chat.
- **Sign in with Swop** for your own app's users is coming with [Swivy](/docs/swivy). <Status kind="building" />
