Skip to content

Sign-in and consent

What you approve when an app connects, how to manage and revoke connections, and the OAuth flow for client developers.

Updated

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 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). 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).

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.

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. 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.
  • 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:

{
  "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.

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.

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 with that store: an empty list means the connection no longer reaches that store (see Errors). Within seconds of the connection reaching no business, it lists only list_merchants, which answers none: send the seller through sign-in again.

Type to search…

↑↓ navigate↵ selectEsc close