---
lastModified: 2026-11-19
title: Sign in with OAuth
description: How a client signs in to the Runner MCP server, which scopes it can ask for, and what to do when the sign-in fails.
sidebar:
  label: Sign-in and scopes
---

Most clients do all of this for you. Read it when you build your own client, or when a sign-in fails.

## The flow, in six steps

1. **Call without a token**

    Send a JSON-RPC request with `POST` to `https://api.runnerai.com/mcp`. Without a token, Runner answers HTTP 401 with this header:

    `WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write"`

2. **Read the resource metadata**

    It names the authorization server: `https://www.runnerai.com/api/auth`.

3. **Register the client**

    Register at `https://www.runnerai.com/api/auth/oauth2/register`. Use a redirect URI on `http://localhost`, `http://127.0.0.1`, or `http://[::1]`. Runner accepts any port and path. Runner accepts 5 registrations each minute from one IP address.

4. **Send the user to sign in, with PKCE**

    Use PKCE with `S256` and send `resource=https://api.runnerai.com/mcp`. The user chooses the workspace and the access.

5. **Call with the token**

    Send the access token in the `Authorization: Bearer` header. Runner answers each request with JSON and keeps no session. A `GET` request gets HTTP 405.

6. **Refresh the token**

    An access token lasts 1 hour. Use the refresh token to get a new one. A refresh token expires after 30 days without use.

## Scopes

| Scope | On the sign-in page | What the client can do |
| --- | --- | --- |
| `store:read` | **Read**, always on | See store data, such as products, orders, and reports. |
| `store:write` | **Make changes**, starts off | Change store data, such as products, prices, and discounts. Ask for it only if your client changes data. |

Use the scopes from the resource metadata or the `WWW-Authenticate` header. The authorization server metadata also lists scopes for other Runner servers. If the client asks for them too, Runner removes them.

## Rules for every client

- **Call from your back end.** Runner refuses requests that come from a web page on another site. Use your server, or a page on `localhost`.
- **One workspace for each connection.** For a second workspace, add the server again under another name and sign in again.
- **Your permissions apply.** Each call uses your Runner permissions and your plan. The list of tools depends on both.

## If sign-in fails

| What you see | What to do |
| --- | --- |
| `{"error":"invalid_scope"}` in the browser | Ask for `store:read`, and `store:write` only if the client changes data. |
| **This redirect URI cannot receive Merchant MCP codes.** | The client sends the browser back to an app link or a web page. Use the `mcp-remote` bridge. |
| **Request the Merchant MCP resource alone.** | Send `resource=https://api.runnerai.com/mcp`, or use the `mcp-remote` bridge. |
| HTTP 429 when the client registers | More than 5 registrations in one minute from one IP address. Wait one minute, then try again. |

More errors are in [Didn't work?](/en/build/quickstart#troubleshooting).
