---
title: "Sign-in and consent"
description: "What you approve when an app connects, how to manage and revoke connections, and the OAuth flow for client developers."
---

> 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 and consent

When you add Sherpo to an AI client, the client sends you to Sherpo to approve the connection. You choose the businesses, the stores and what the app may do in each, and how long the connection lasts. Each connection is listed on your **Connections** page, where you can revoke it at any time.

## What you approve

The client opens the merchant app's **Connect an app** page. If you're signed out, you sign in first and come back to it.

The page is titled with the app's name, such as **Connect Claude to Sherpo**, or, for an app Sherpo doesn't know, the name it gave itself in quotes, such as **Connect “My agent” to Sherpo**: "It will act for you on the stores you pick." **Access is sent to** shows the host the client receives access at, or "Not given".

### The unverified app warning

Claude, ChatGPT and Perplexity are known by where they receive access, so when they connect to Sherpo's MCP server they show by name, with no warning. Any other app registers itself, so it carries the **Unverified app** tag, as Sherpo hasn't checked who made it. For an app named My agent that receives access at `your-client.example`, the page warns:

> “My agent” registered itself, and Sherpo hasn't checked who made it. Continue only if you just started connecting from it and you trust your-client.example.

When the app receives access on your own computer (a local address), the warning reads:

> “My agent” registered itself, and Sherpo hasn't checked who made it. It sends access to an app on your own computer, so continue only if you just started connecting from it.

Continue only if you just started connecting from that app.

### Businesses it may act on

Each business you're in with a store is a card. If you're in more than one, check the businesses the app may act on under **Businesses it may act on**, at most 100: "Open a business to pick its stores and what it may do there." The first is checked, unless your seat there may not connect apps, and the cards start closed, each checked one naming what the app may do there and how many stores it reaches. A business where your seat may not connect apps shows "Your seat here may not connect apps." and can't be checked. A single business shows its card open, with no box to check.

If you have no store yet, the page says: "Connecting an app needs a store. Create one, then start again from your app."

### Stores

Open a business's card to see its stores, each one listed checked by default; the card shows how many are picked, such as **3 of 3 stores**. With many stores, **Show more stores** lists the rest, checked too while every store shown before is, up to 100 in all: past that, they stay unchecked. Keep them, or uncheck the ones the app shouldn't reach. At least one must stay checked in each business, and at most 100 may be; a card with none, or with too many, stays open until that's fixed.

### What it may do

Pick one set for each business, under its stores in its card. Each one lets the app read, change and remove what it covers:

| Set | What it covers |
| --- | --- |
| Catalog | Products, prices and discounts. |
| Content | The website, pages, files, quizzes and certificates. |
| Sales | Orders, revenue, subscriptions and affiliates. |
| Customers | Customers, reviews and event check-in. |
| Portfolio | Portfolios and their holdings. |
| Everything | Everything an app may do through Sherpo's MCP server. |

Everything is picked by default. There is no read-only choice. A set is "Never more than your own seat allows": it's cut to your own permissions in the business, and a set your seat holds nothing of isn't offered. [Scopes](/merchant-mcp/scopes) lists the scopes each set holds.

### Expires

Pick how long the connection lasts: **30 days**, **90 days** (the default), **A year** or **Never**. A connection set to Never works until you revoke it.

### Earlier connections to disconnect

If you connected the same app to a business you picked before, the page lists those connections, each with the date it was connected. For an app connection, the entry names the businesses on the page it reaches, such as "Reaches My Business and Other Business. Only the businesses you connect now lose it." None is checked, so they stay. Check the ones to disconnect once this one is made: each loses the businesses you picked now, and one reaching only those ends. Access they granted and affiliates they made stay until you end them, and automations they created keep running until you pause them (see [Revoke a connection](#revoke-a-connection)). Reconnecting never replaces an earlier connection on its own.

If a disconnect can't be confirmed, your Connections page says so, naming the connection: revoke it there if it still reaches a business you disconnected. For a connection made before connections could reach several businesses, a banner in every business says so instead, naming the business it was made for: its Open API tokens link goes to that business's API tokens page, where you revoke it if it's still listed. The banner goes once it's revoked. These notices show only in the browser you connected from, for up to 30 days or until you sign out, so after disconnecting earlier connections, check your Connections and API tokens pages yourself. If one you picked can't be found at all, Connections warns for a day that it may still be active: check your connections and API tokens.

### Who may connect

In each business you pick, you need to be a member allowed to create API tokens, as every member with full access is. Otherwise, with a single business, the page says "Connecting an app needs permission to create API tokens, which your seat here doesn't have. Ask a member of the business with full access." and Connect is turned off. Among several, that business can't be checked (see [Businesses it may act on](#businesses-it-may-act-on)).

The connection is listed on your **Connections** page under the app's name, and it isn't one of your API tokens. You may hold 100 live app connections; your API tokens don't count toward them. At that many, the page shows **Too many connections**: "You hold 100 app connections, the most you may. Revoke one on your Connections page, then connect again from the app."

### Connect or Cancel

**Connect** makes the connection and sends you back to the app. **Cancel** sends you back without one, and the app is told access was denied.

Connect waits until Sherpo has read your access in the business, saying "Still reading your access." meanwhile. If you're offline, it says "You’re offline. Your access loads once you’re back online." and goes on by itself once you're back online.

### Expired or handled links

The link from your app lasts 10 minutes. After that, or for a link Sherpo doesn't know, the page shows **This link expired**: "This link expired. Start again from your app."

If the request was already answered, for example in another tab, the page shows **Already handled**: "This connection was already answered, maybe in another tab. Go back to the app."

## Manage your connections

Your connections are on the **Connections** page: open the account menu, then **Connections**. It lists the apps and tools that act as you, each reaching the businesses you picked. Only you see yours, and the page needs no permission.

Each row shows the connection's name, after the app, and its status (**Active**, **Expired** or **Revoked**), where it can be used (**MCP** for an app you connected here), when it was created and last used, when it ends (**Until** a date, or **Until revoked**), and each business it reaches with its stores there.

Under each business it reaches, the row also shows the connection's limits there: its rate (the default of 600 calls a minute unless you set one) and its quota (**No quota** unless you set one).

A connection's menu (**Actions for My agent**, for a connection named My agent) has, for each business it reaches:

- **Edit limits in** a business: sets how often the connection may call each store of that business, and an optional quota of calls a day or a month. See [Limits](/merchant-mcp/limits). Only while the connection is live, and it needs the **Edit** permission on **API tokens** in that business.
- **What it made or changed in** a business: lists the access it granted, the affiliates it made or changed and the automations it created there that still stand, also once the connection ended. A business it reached again lists each time apart, by when it began: the menu holds the latest four that reach a store you can open, and the list links the rest. It needs a permission to view customers, affiliates or automations in that business.
- **Remove from** a business: ends it in that business alone, and it keeps working in the others. It's offered while the connection reaches more than one business.

and, while the connection is live, **Revoke**, which ends it in every business it reaches.

The actions of another business than the one you're in open on one of its stores, so they follow your permissions there.

A connection that no longer reaches any business ends on its own: it shows **Revoked**, no longer counts toward your connections, and the app's next call is refused so it must connect again.

### Revoke a connection

Revoking asks you to confirm: "It stops working in every business it reaches right away, and the webhook endpoints, integrations and redirects it set up are turned off. This can’t be undone. Access it granted and affiliates it made or changed stay until you end them, and automations it created keep running until you pause them. You’ll find them under What it made or changed in each business." Click **Revoke**. The app's next call is refused and it must connect again.

Removing it from a business asks the same for that business alone: "It stops working in My Business right away and keeps working in the other businesses it reaches. The webhook endpoints, integrations and redirects it set up in My Business are turned off. This can’t be undone. Access it granted and affiliates it made or changed there stay until you end them, and automations it created keep running until you pause them. You’ll find them under What it made or changed in My Business." Click **Remove**. The app stays connected, and its calls on that business's stores are refused with a `not_permitted` tool error.

When it reached the store you're in, what it left behind there then shows under **Made or changed by My agent**:

- **Access it granted:** **End** takes a customer's access away.
- **Affiliates it made:** **End** stops the affiliate earning. Commissions they already earned stay.
- **Affiliates it changed:** **Restore** puts back what the affiliate earned before.
- **Automations it created:** **Pause** stops the automation. What it already unlocked or lowered stays.

The list covers one store. Below it, the connection's other stores, in this business and the others it reached, each link to what it made or changed there. You can come back to it later with **What it made or changed in** a business.

### Connections made before

A connection made before connections could reach several businesses acts for one business and is one of your API tokens there, named after the app, on your **API tokens** page (account menu, then **API tokens**). It keeps working until it expires or you revoke it. Its row shows **Reaches** with its stores and "MCP only", and three actions named after it: **Edit limits of My agent**, **What My agent made or changed** and **Revoke My agent**.

- **Edit limits** sets how often the connection may call each store, and an optional quota. See [Limits](/merchant-mcp/limits).
- **What it made or changed** lists the access it granted, the affiliates it made or changed and the automations it created that still stand.
- **Revoke** ends the connection, after you confirm with **Revoke token**: "Anything using it stops working right away, and the webhook endpoints, integrations and redirects it set up are turned off. This can’t be undone. Access it granted and affiliates it made or changed stay until you end them, and automations it created keep running until you pause them. You’ll see any of them next."

What it left behind then shows under **Made or changed by My agent**:

- **Access it granted:** **End** takes a customer's access away.
- **Affiliates it made:** **End** stops the affiliate earning. Commissions they already earned stay.
- **Affiliates it changed:** **Restore** puts back what the affiliate earned before.
- **Automations it created:** **Pause** stops the automation. What it already unlocked or lowered stays.

You can come back to this list later with **What My agent made or changed**.

### Losing access to a business

If you leave a business or are removed from it, your connections stop reaching it, and keep working in your other businesses. A connection that reached only that business ends. If you join it again, connect again. A member of the business with the access may also remove your connection from it, under **App connections** on its **Members** page in **Business settings**, which ends it too when it reaches no other business.

## For client developers

The server is an OAuth 2.1 authorization server and the protected resource in one, at the same origin as the MCP endpoint (`https://mcp.sherpo.io`). A standard MCP client with OAuth support needs nothing beyond this section. All paths below are on that origin.

### Discovery

- Protected resource metadata: `/.well-known/oauth-protected-resource` names the resource (the origin) and its authorization server (the same origin).
- Authorization server metadata: `/.well-known/oauth-authorization-server` lists the endpoints and `scopes_supported`, the scopes a connection may hold.

A call without a token answers `401` with a `WWW-Authenticate: Bearer` challenge whose `resource_metadata` names the protected resource metadata URL. Use the URL the challenge names.

### Register the client

Register with dynamic client registration (RFC 7591) at `POST /oauth/register`:

```json
{
  "client_name": "My agent",
  "redirect_uris": ["https://your-client.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

It answers `201` with your `client_id`.

- A public client sends `"token_endpoint_auth_method": "none"`. A confidential client uses `client_secret_basic` (or `client_secret_post`) and gets a `client_secret`.
- `client_name` is what the consent screen shows. Sherpo cleans it of characters that could disguise it and cuts it to 120 characters. A name left empty is dropped, and the app is shown by its redirect host.
- A registration that never connects is removed after 30 days. Register again when that happens.
- Registration is rate limited per network: past the limit it answers `429` with `temporarily_unavailable`, usually with a `Retry-After` header. See [Limits](/merchant-mcp/limits).

Dynamic registration is the only way to get a `client_id`.

### Authorize

Send the seller's browser to `GET /authorize` with:

- `response_type=code`, `client_id`, `redirect_uri` and `state`;
- `code_challenge` and `code_challenge_method=S256`;
- optionally `resource` and `scope`.

PKCE with `S256` is required. Without it, the browser is sent back to your redirect URI with `error=invalid_request` and the description "PKCE with S256 is required."

The `scope` you ask for doesn't decide the grant: the seller picks a set on the consent screen. If the seller cancels, or holds as many app connections as they may, you get `error=access_denied`.

An unknown client or a redirect URI it didn't register shows an error page in the browser and never redirects.

### The resource indicator

`resource` (RFC 8707) must be the server's origin, `https://mcp.sherpo.io`. Naming the URL with `/mcp` as the resource is refused with `invalid_target`. Leaving `resource` out works too. Either way, the token serves both the origin and `/mcp`.

### Tokens

Exchange the code at `POST /oauth/token` (form-encoded) with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier` and, if you sent one at authorize, `resource`. A wrong verifier is `invalid_grant`.

- **Access tokens** last up to 1 hour, less when the connection ends sooner.
- **Refresh tokens** live as long as the connection: until the expiry the seller picked, or with no end for a connection that never expires. Near the connection's end, a refresh is refused with `invalid_grant` and "The connection has expired."
- **Rotation:** every refresh answers a new refresh token. If you lost the answer, you may retry with the refresh token just replaced for 60 seconds. Reusing an old refresh token after that ends the whole connection, with `invalid_grant` and "The refresh token was already used; connect again."
- **Scopes are fixed:** a refresh can't change them. Leave `scope` out, or send exactly the grant's scopes. Anything else is refused with `invalid_scope` and "Ask for the grant's own scopes; a narrower grant takes a new consent."

### Revoke

Revoke at the token endpoint (RFC 7009) with the access token or the refresh token. Either one ends the whole connection, in every business it reaches, and it shows as Revoked on the seller's Connections page, or, for a connection made before connections could reach several businesses, on the API tokens page of its business.

### 401 and 403 at the MCP endpoint

- **`401` with `error="invalid_token"`:** the token is missing, wrong or expired, or the connection was revoked or expired. For a connection made before connections could reach several businesses, so does the seller leaving or being removed from its business. An access token lasts up to 1 hour, and an expired one answers this same `401` while its refresh token still works. Refresh the token first. Only when the refresh fails with `invalid_grant` (the connection was revoked, expired or ended), or a refreshed token is refused again, send the seller through sign-in again.
- **`403` with `error="insufficient_scope"`:** the tool needs a scope the connection doesn't hold. The connection stays, and other tools keep working. Since a connection's scopes never change, more access takes a new consent with a wider set. For a connection reaching several businesses, a scope a tool declares that the store's business lacks while another business it reaches holds it is a tool error instead, with only its text, and the connection keeps its tools: "The connection lacks the scope this tool needs on this store's business; another business it reaches holds it."

Both carry `resource_metadata` in the `WWW-Authenticate` header. When the answer was already streaming, a `401` or `403` arrives as a tool error carrying only its text: "The connection was revoked or expired; connect again." or "The connection lacks the scope this tool needs." A scope a call needs for its arguments (such as the read scopes of a webhook's events) still answers `403` when the store's business lacks it. A tool call refused for any other reason is a tool error, not an HTTP error: see [Errors](/merchant-mcp/errors).

A business removed from a connection answers its stores' calls with a `not_permitted` tool error, not a `401`. To tell this from a record the connection may not act on, call [`list_merchants`](/merchant-mcp/tools/list_merchants) with that `store`: an empty list means the connection no longer reaches that store (see [Errors](/merchant-mcp/errors)). Within seconds of the connection reaching no business, it lists only [`list_merchants`](/merchant-mcp/tools/list_merchants), which answers none: send the seller through sign-in again.

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