---
title: "Sign-in"
description: "How you sign in to a store from your AI assistant and choose what it may do, and how an MCP client gets and renews its token."
---

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

# Sign-in

A connection always acts for one signed-in customer of one store. Nobody signs in for you: the first time your client connects, it opens the store's sign-in page in your browser, and the access you approve there is all the client gets.

## Signing in

1. **Your client opens the store's sign-in page.** It shows the store's name, icon and colors, the app asking (Claude, ChatGPT or Perplexity are named as such; any other app by the name it gave itself, marked unverified until the store verifies it) and where it sends you back once you're done.
2. **You sign in with your email.** Enter the address you use at the store, then the code mailed to you; a quick check that you're not a bot may run first. You can sign in with Google instead.
3. **You choose what the app may do.** The consent screen lists what the app asked for. Pick **Full access** to grant all of it, or **Read-only** to let it read without changing anything (offered when it asked to read and more).
4. **You're sent back to your client**, which is now connected.

Signing in here signs you in to this authorization alone: it never signs you in to the store's site, and signing out of the store's site leaves the connection as it is.

The customer MCP works for the customers of every store, whatever the store's plan.

## What an app may ask for

Each permission is a scope. The consent screen names each one the app asks for, as below, and the app lists only the tools its scopes cover.

| Scope | On the consent screen | Tools it opens |
| --- | --- | --- |
| `read` | See your purchases, subscriptions and progress, and read your unlocked content | Every [tool](/customer-mcp/tools) that reads, and the store's [prompts](/customer-mcp/prompts) |
| `profile:write` | Change your name and preferences | [`update_profile`](/customer-mcp/tools/update_profile), [`mark_notifications_read`](/customer-mcp/tools/mark_notifications_read), [`delete_notifications`](/customer-mcp/tools/delete_notifications), [`update_notification_settings`](/customer-mcp/tools/update_notification_settings) |
| `progress:write` | Update your progress | [`complete_entry`](/customer-mcp/tools/complete_entry) |
| `quiz:write` | Take quizzes for you | [`start_attempt`](/customer-mcp/tools/start_attempt), [`save_attempt`](/customer-mcp/tools/save_attempt), [`submit_attempt`](/customer-mcp/tools/submit_attempt), [`forfeit_quiz`](/customer-mcp/tools/forfeit_quiz) |
| `review:write` | Write and delete your reviews | [`write_review`](/customer-mcp/tools/write_review), [`delete_review`](/customer-mcp/tools/delete_review) |
| `subscription:write` | Cancel and resume your subscriptions | [`cancel_subscription`](/customer-mcp/tools/cancel_subscription), [`resume_subscription`](/customer-mcp/tools/resume_subscription), [`change_subscription_plan`](/customer-mcp/tools/change_subscription_plan) |

Two tools need no scope at all, so every connection has them: [`get_store`](/customer-mcp/tools/get_store) and [`verify_certificate`](/customer-mcp/tools/verify_certificate). An app may also ask for `checkout:write` ("Start purchases for you"), which the store's API uses; it opens no MCP tool, and the consent screen warns about it for an app the store hasn't verified.

> **Unverified apps**
>
> An app that registered itself and that the store hasn't verified can't resume a subscription or change its plan, whatever you grant it: the call is refused, and you can do either from your account on the store's site, at `/account/subscriptions`. Every MCP client registers itself, so this applies to most of them.

## How long a connection lasts

- The client holds an access token, which lasts an hour, and a refresh token, which lasts 30 days. Every refresh hands it a new pair and retires the old refresh token, so a connection you keep using stays signed in; one unused for 30 days asks you to sign in again.
- A token works for the store it was issued for, and only on its MCP server: it can't be used on another store, or on the store's API.
- Disconnecting it under **Connected apps** in your account on the store's site (`/account/connected-apps`) ends its access at once: its tokens are revoked, and its next call is refused.
- Removing the connector or server in your client stops it using the store. A client that revokes its token when you remove it ends its access at once; otherwise its access ends when its last access token expires, within the hour, as long as it no longer holds the refresh token.

## For developers

This is the flow every client above runs. It is standard MCP authorization: OAuth 2.1 with dynamic client registration (RFC 7591), PKCE (S256 only), protected resource metadata (RFC 9728) and authorization server metadata (RFC 8414). A client built on an MCP SDK gets all of it from the SDK; the requests below show what goes over the wire, for the store `shop.example.com` on its own host.

### 1. Find the authorization server

A request with no token is refused with `401` and a pointer to the endpoint's metadata:

```http
POST /mcp HTTP/1.1
Host: shop.example.com
Content-Type: application/json
Accept: application/json, text/event-stream

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://shop.example.com/.well-known/oauth-protected-resource/mcp"
```

```sh
curl https://shop.example.com/.well-known/oauth-protected-resource/mcp
```

```json
{
  "resource": "https://shop.example.com/mcp",
  "authorization_servers": ["https://customer-auth.sherpo.io/s/shop.example.com"],
  "scopes_supported": ["read", "profile:write", "review:write", "quiz:write", "progress:write", "subscription:write"],
  "bearer_methods_supported": ["header"],
  "resource_name": "shop.example.com on Sherpo"
}
```

`scopes_supported` lists the scopes the MCP tools and prompts use. Then read the authorization server's metadata. On the store's host it names the store's own endpoints (the grants an MCP client uses are `authorization_code` and `refresh_token`; the store's own sites use the others):

```sh
curl https://shop.example.com/.well-known/oauth-authorization-server
```

```json
{
  "issuer": "https://customer-auth.sherpo.io/s/shop.example.com",
  "authorization_endpoint": "https://shop.example.com/authorize",
  "token_endpoint": "https://shop.example.com/token",
  "registration_endpoint": "https://shop.example.com/register",
  "revocation_endpoint": "https://shop.example.com/revoke",
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code", "refresh_token", "…"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "revocation_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "scopes_supported": ["read", "profile:write", "checkout:write", "review:write", "quiz:write", "progress:write", "subscription:write"],
  "authorization_response_iss_parameter_supported": true
}
```

The issuer is `https://customer-auth.sherpo.io/s/{store}` for both addresses of the server. Connected at `https://mcp.sherpo.io/s/{store}` instead, the protected resource metadata is at `https://mcp.sherpo.io/.well-known/oauth-protected-resource/s/{store}` (and `.../s/{store}/mcp` for the `/mcp` form), and the authorization server's at `https://customer-auth.sherpo.io/.well-known/oauth-authorization-server/s/{store}`, with its endpoints under the issuer (`/authorize`, `/token`, `/register`, `/revoke`). Follow the `resource_metadata` the `401` names: the metadata at `https://mcp.sherpo.io/.well-known/oauth-protected-resource` belongs to the merchant MCP server, so a client that skips it and reads the host's root finds the wrong server. Prefer the store's own address, where every document is at the root.

### 2. Register the client

```sh
curl https://shop.example.com/register \
  -H 'content-type: application/json' \
  -d '{
    "client_name": "My study app",
    "redirect_uris": ["http://127.0.0.1:8976/callback"],
    "token_endpoint_auth_method": "none"
  }'
```

```json
{
  "client_id": "CLIENT_ID",
  "client_id_issued_at": 1793678400,
  "client_name": "My study app",
  "redirect_uris": ["http://127.0.0.1:8976/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "read profile:write checkout:write review:write quiz:write progress:write subscription:write"
}
```

- `token_endpoint_auth_method` is `none` (a public client, the usual choice), or `client_secret_basic` or `client_secret_post` for a client that keeps a secret: the answer then carries `client_secret`, shown once. PKCE is required either way.
- A client that names no `scope` may ask for every scope listed in `scope`. The name is cleaned and cut to 120 characters; the answer says what was kept.
- Registrations are per store: register once with each store you connect to. A registration that hasn't completed a sign-in within a day lapses, and one the store hasn't verified that holds no live token and goes unused for 30 days is removed. When `/token` answers `invalid_client`, register again.

### 3. Send the customer to sign in

Open the authorization endpoint in the customer's browser, with a PKCE challenge (S256) and the endpoint as `resource`:

```text
https://shop.example.com/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A8976%2Fcallback
  &scope=read%20progress%3Awrite
  &state=STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fshop.example.com%2Fmcp
```

`resource` is the server's address as you connect to it: `https://{store}/mcp`, or `https://mcp.sherpo.io/s/{store}` (its `/mcp` form too). A token for any of them works on all of them. Once the customer approves, the browser comes back to `redirect_uri` with `code`, `state` and `iss`; check that `iss` is the issuer and `state` is yours. A refusal comes back as `error` (`access_denied` when the customer declines).

### 4. Exchange the code

```sh
curl https://shop.example.com/token \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d redirect_uri=http://127.0.0.1:8976/callback \
  -d client_id=CLIENT_ID \
  -d code_verifier=CODE_VERIFIER \
  -d resource=https://shop.example.com/mcp
```

```json
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "read progress:write"
}
```

`scope` is what the customer granted, which may be less than you asked for (Read-only grants `read` alone). Send the token on every request to the endpoint as `Authorization: Bearer ACCESS_TOKEN`.

### 5. Refresh and revoke

```sh
curl https://shop.example.com/token \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN \
  -d client_id=CLIENT_ID
```

The answer has the same shape, with a new refresh token: keep it and drop the old one, which no longer works. When the customer disconnects, revoke the token (RFC 7009): revoking either the access or the refresh token ends the connection.

```sh
curl https://shop.example.com/revoke \
  -d token=REFRESH_TOKEN \
  -d client_id=CLIENT_ID
```

A client with a secret authenticates each `/token` and `/revoke` request with it, by HTTP Basic or in the body, as it registered.

Errors come back as OAuth's:

- At the authorization endpoint, once the client and its redirect are accepted, as `error` on the redirect: `access_denied` when the customer declines, `invalid_scope` for a scope the app may not hold, `invalid_target` for a `resource` that isn't this store's server, `invalid_request` for a malformed request, `unsupported_response_type` for any `response_type` but `code`, `unauthorized_client` when the registration lapsed or was removed meanwhile (register again), `temporarily_unavailable` when too many calls came in (try again later), and `server_error` for a failure on Sherpo's side. Before that (an unknown client, a redirect it didn't register), the customer sees an error page instead and nothing is redirected.
- At the token endpoint, as JSON: `invalid_grant` for a code or refresh token that is wrong, used or expired (sign the customer in again), `invalid_client` (register again), `invalid_request`, `unsupported_grant_type`, and `temporarily_unavailable` with `Retry-After` when too many calls or refused requests came from your network, or `503` while the store is unavailable. `server_error` means the failure was on Sherpo's side; try again.

Source: https://docs.sherpo.io/customer-mcp/sign-in/index.mdx
