OAuth Protocol Reference

The server records a pending request. It then redirects to the consent page carrying only ?request_token=<requestToken>.

Endpoints

All URLs are built from your configured issuer. The issuer must therefore be the public base URL the client can reach.

Dynamic Client Registration is deprecated by the MCP specification as of 2026-07-28. The plugin still serves it for compatibility.

Consent decisions are not endpoints in that table. Each one is an authorizeMcpClient mutation: an administrator's decision on the Admin API, a customer's on the Shop API.

The token, /register and /revoke endpoints accept an application/x-www-form-urlencoded body, the format OAuth 2.1 requires (RFC 6749). They also accept an application/json body.

The authorization-server metadata advertises:

• S256 PKCE
• the authorization_code and refresh_token grants
• token_endpoint_auth_methods_supported: ["none"], meaning public clients
• client_id_metadata_document_supported: true, the flag MCP clients check before sending a URL client_id

The client_id metadata document

The server fetches exactly the address the client sends, then compares that address against the document character for character. Send a URL already in the form a URL parser produces.

How the server fetches it:

• Redirects are not followed.
• Hosts that resolve to private or other special-use addresses are refused.
• The response is capped at 5 KB.
• The document is cached for one hour, then fetched again.
• At most 8 document fetches run at once, and each one times out after 5 seconds.

What the document must contain:

• client_id (string) — Must equal the URL the client sent, exactly.
• client_name (string, 255 characters maximum) — The client's name.
• redirect_uris (array of strings, each 255 characters maximum) — The redirect URI the client uses must appear here exactly. The same length limit applies to URIs sent to /mcp/oauth/register.

To develop against a metadata document served from your own machine, set oauth.allowLoopbackCimdDocuments: true. It permits a client_id URL pointing at localhost, 127.0.0.1, or ::1 over plain HTTP.

The server refuses to start with the option enabled when NODE_ENV is production.

Resource and toolset

Every authorization request names a resource, and the resource decides which toolset the grant is for.

A resource that matches neither is rejected. So is one carrying a query string or a fragment. The token the client receives is scoped to that one toolset.

Token lifetimes and rotation

Both values are tuned through McpOauthOptions.

• accessTokenTtlSeconds (number, default: 900) — How long an access token lasts, which is 15 minutes.
• refreshTokenTtlSeconds (number, default: 2592000) — How long a refresh token lasts, which is 30 days.

Refresh rotates. Each refresh issues a new refresh token and invalidates the previous one. Reusing a refresh token that has already been rotated revokes the entire grant. OAuth 2.1 treats reuse as a sign the token was compromised.

Revoking a grant keeps its database row and sets revokedAt, so the audit trail survives. The token stops working immediately.

Sessions, revocation, and expiry

The grant's session

Exchanging the authorization code creates one internal Vendure session for the grant. That session carries an ordinary random token generated by Vendure. The token stays server-side and is never returned to the MCP client, which only ever holds the OAuth access and refresh tokens.

The session's lifetime is Vendure's ordinary sliding expiry, the same as any other session. Using it extends it, because Vendure pushes the expiry out once it is more than halfway to expiring. An agent in regular use keeps its session for as long as it keeps working. There is no separate maximum age for MCP sessions.

What survives a refresh

A refresh rotates the OAuth token pair and leaves the session untouched. Anything the session holds survives:

• the active order
• the active channel
• custom fields

The rotation is written in a single transaction. If the response is lost after the commit, the client still holds the old token. Its retry then presents a token the server has already rotated. The server treats that as reuse, revokes the whole grant and deletes its session. The user must authorize the client again.

What ends a session

• Revocation. This deletes the session row and drops its cache entry, in the same operation that marks the grant revoked. On a single instance the credential stops working straight away. If you run several instances with the default in-memory cache, the other instances keep accepting the cached session for up to 5 minutes, the sessionCacheTTL. A shared cache fixes that. See Horizontal scaling.
• The daily retention task. This deletes the session of any grant that has passed its own expiry. That is the case where a client stopped refreshing for longer than refreshTokenTtlSeconds. The task runs once a day, at 03:30 by default, set through oauth.retentionSchedule. Session deletion can therefore lag the grant's expiry by up to a day. If the task is not running, the session remains until it expires on its own.
• Natural expiry. A session can lapse while its grant is still valid. The next MCP request creates a replacement, so a lapsed session never breaks a working grant.

Rotating the secret or the issuer

Rotating oauth.tokenSecret or changing oauth.issuer stops every existing token working at once. Every call is refused and every refresh fails, so each agent must authorize again.

The old grants are not revoked. They live until their own expiry, and the retention task removes their sessions then, up to refreshTokenTtlSeconds plus a day. Revoking the grants removes their sessions right away. Nothing about those sessions can be derived from the old access tokens.

Why a request is refused

Failed token requests return 400 with a standard OAuth error body:

Use the error field for handling, not the description.

• invalid_grant: code or refresh token is invalid → start a new auth flow
• invalid_request: missing or malformed parameter
• unsupported_grant_type: grant type not supported
• invalid_target: missing or invalid resource (must be a toolset URL)

Client registration failures follow the same format, using:

• invalid_client_metadata
• invalid_redirect_uri

Rate limits return 429 with error: "rate_limit_exceeded" and retry_after_seconds in the body. Prefer the Retry-After header.

Refusals of the consent decision itself are covered in the oauth-consent troubleshooting table. That covers a mismatched Origin header, an unset consent URL, and a user holding an administrator record.

Rate-limit refusals on the MCP endpoints themselves, as opposed to the OAuth endpoints above, are covered in What a rate-limited caller sees.

See also

• OAuth & Consent Integration — the admin and customer consent pages this flow redirects to
• Assistant outside Vendure — a first-party client that runs this flow invisibly
• Production Hardening — the issuer guard, token secret rotation, and rate limits protecting these endpoints