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

# Authentication

> How a client authenticates to the storekit merchant MCP: OAuth 2.1 with protected-resource discovery and a storekit dashboard sign-in.

The merchant MCP authenticates with OAuth 2.1. Every tool call is scoped to the account the token resolves to; nothing in a tool's arguments can change that.

|          | OAuth (sign-in)                                                                                  |
| -------- | ------------------------------------------------------------------------------------------------ |
| Header   | `Authorization: Bearer <token>`                                                                  |
| Identity | A storekit dashboard user                                                                        |
| Account  | The user's first account                                                                         |
| Needs    | An account on the beta waitlist — [request access](https://t09czsyu90l.typeform.com/to/G6rIJWNv) |

An unauthenticated request receives `401` with a `WWW-Authenticate` header (below).

## OAuth

The endpoint is an OAuth 2.1 protected resource. The authorisation server is hosted by [Scalekit](https://www.scalekit.com), with the login itself delegated to the storekit dashboard, so a user signs in with their normal storekit credentials.

<Steps>
  <Step title="Discovery">
    An unauthenticated `POST /mcp` returns:

    ```http theme={null}
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.storekit.com/.well-known/oauth-protected-resource"
    ```

    `GET` that URL for the protected-resource metadata:

    ```json theme={null}
    {
      "resource": "https://mcp.storekit.com",
      "authorization_servers": ["https://storekit.eu.scalekit.com/resources/res_143363546435027719"],
      "bearer_methods_supported": ["header"],
      "scopes_supported": ["read"]
    }
    ```

    The authorisation server's own metadata is at its `/.well-known/oauth-authorization-server` path, as usual. Clients register themselves with it; there is no client ID or secret to configure. Clients supporting the MCP authorisation spec (Claude, ChatGPT, Cursor, VS Code, Claude Code) do all of this without configuration.
  </Step>

  <Step title="Sign-in">
    The authorisation server redirects the user to the storekit dashboard, which shows **Connecting your MCP client, please wait...** while it confirms the login request with the storekit API, then redirects back to the client. A user who is not signed in to the dashboard signs in first. If the user belongs to several accounts, the token resolves to their **first** account; there is no account picker.
  </Step>

  <Step title="Calls">
    Send the access token as `Authorization: Bearer`. The token's `sub` is the storekit user; its `scope` claim is attached to the request as `scopes` (defaulting to `read`). Refresh as your OAuth library dictates; an expired token gets a `401` and the client re-runs discovery.
  </Step>
</Steps>

<Info>
  Dashboard user roles and per-venue access do not apply to MCP. A token for a user who can see one venue in the dashboard reads every venue on the account, and can call the two write tools. Choose who connects accordingly — see [Permissions & Privacy](/docs/guides/ai/permissions-and-privacy).
</Info>

## Checking the Endpoint

An unauthenticated call is enough to confirm the server is reachable and to see the discovery header a client follows:

```bash theme={null}
curl -si https://mcp.storekit.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Expect `401 Unauthorized` with the `WWW-Authenticate` header shown above. Questions about access or the beta: [mcp@storekit.com](mailto:mcp@storekit.com).

## Origin and Host Checks

Requests carrying an `Origin` header are checked against storekit's allow-list of browser origins when one is configured, and rejected with `403` before authentication if they do not match. Requests without an `Origin` header — every desktop client, CLI and server — pass straight to authentication. The `Host` header must match the public hostname.

## Rate Limit

60 requests per rolling minute, keyed by user (by IP before authentication). Exceeding it returns HTTP `429` with a `Retry-After` header, outside the MCP envelope.


## Related topics

- [Email Deliverability](/docs/guides/notifications/email-deliverability.md)
- [Security Policy](/docs/privacy-security/security-policy.md)
- [Connect Claude Code](/docs/guides/ai/connect/claude-code.md)
- [TISSL](/docs/guides/integrations/pos/tissl.md)
- [Zonal (Aztec)](/docs/guides/integrations/pos/zonal.md)