Skip to main content

OAuth Endpoints

The Perspective API exposes six endpoints to support the MCP authorization flow. Two are standard OAuth2 discovery documents; three proxy the authorization-code flow to Auth0 (the authorization redirect, the callback that relays the code back to the client, and the token exchange); one handles dynamic client registration.

All endpoints are on the base URL https://api.perspective.co.


GET /.well-known/oauth-protected-resource​

Returns the OAuth 2.0 Protected Resource Metadata document for the MCP endpoint. MCP clients fetch this after receiving a 401 response with a WWW-Authenticate: Bearer resource_metadata="..." header.

Response (200 application/json):

FieldValue
resourceThe base URL of the protected resource (e.g. https://api.perspective.co)
authorization_serversArray containing the MCP server origin (e.g. https://api.perspective.co) — this server also hosts the authorization-server metadata, and its issuer is this same value
scopes_supported["offline_access", "openid"]
bearer_methods_supported["header"]
resource_documentationhttps://developers.perspective.co

Example response:

{
"resource": "https://api.perspective.co",
"authorization_servers": ["https://api.perspective.co"],
"scopes_supported": ["offline_access", "openid"],
"bearer_methods_supported": ["header"],
"resource_documentation": "https://developers.perspective.co"
}
note

authorization_servers is always one of the origins configured in the server's MCP_BASE_URL setting: the one matching the request's Host, or the first configured origin if none matches. resource is usually the same origin; only recognised first-party preview deployments advertise their own URL as resource. In production both are https://api.perspective.co.


GET /.well-known/oauth-authorization-server​

Returns the OAuth 2.0 Authorization Server Metadata document. MCP clients use this to discover all the endpoints they need for the authorization-code flow.

Response (200 application/json):

FieldValue
issuerThe MCP server origin (https://api.perspective.co in production). It equals authorization_servers[0] in the protected-resource metadata, as RFC 8414 requires
authorization_endpointhttps://api.perspective.co/oauth/authorize
token_endpointhttps://api.perspective.co/oauth/token
jwks_urihttps://authenticate.perspective.co/.well-known/jwks.json — the Auth0 key set
registration_endpointhttps://api.perspective.co/oauth/register
response_types_supported["code"]
grant_types_supported["authorization_code", "refresh_token"]
token_endpoint_auth_methods_supported["none"] — public clients; no client secret required
code_challenge_methods_supported["S256"] — PKCE required
scopes_supported["offline_access", "openid"]

Example response:

{
"issuer": "https://api.perspective.co",
"authorization_endpoint": "https://api.perspective.co/oauth/authorize",
"token_endpoint": "https://api.perspective.co/oauth/token",
"jwks_uri": "https://authenticate.perspective.co/.well-known/jwks.json",
"registration_endpoint": "https://api.perspective.co/oauth/register",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"token_endpoint_auth_methods_supported": ["none"],
"code_challenge_methods_supported": ["S256"],
"scopes_supported": ["offline_access", "openid"]
}
note

The authorization_endpoint, token_endpoint and registration_endpoint point to the Perspective API, which proxies authorization and token requests to Auth0. Only jwks_uri points directly to Auth0; its domain comes from the AUTH0_DOMAIN environment variable.

:::info Metadata issuer vs. access-token issuer The metadata issuer (https://api.perspective.co) is not the iss claim of the access tokens you receive. The Perspective API proxies OAuth to Auth0, so Auth0 still mints the tokens and their iss is the Auth0 domain, https://authenticate.perspective.co/. Validate a token's signature against jwks_uri, not against the metadata issuer. :::


GET /oauth/authorize​

Proxies the OAuth2 authorization redirect to Auth0. MCP clients redirect the user's browser here; the server checks the client's redirect_uri, substitutes its own callback and appends the required Auth0 audience and connection parameters. Depending on the environment it then either shows a short sign-in choice page ("Continue with Google" or "Continue with email") or redirects straight to the email and password sign-in.

Query parameters:

All standard OAuth2 authorization parameters are accepted (client_id, redirect_uri, response_type, scope, state, code_challenge, code_challenge_method, etc.). Parameters given more than once are dropped rather than forwarded.

redirect_uri is required and must be on the server's allowlist of trusted client callbacks:

  • https callbacks on the hosts of supported MCP clients and integrations (for example claude.ai and chatgpt.com)
  • loopback callbacks for native and CLI clients (RFC 8252): http://localhost, http://127.0.0.1 or http://[::1], on any port and path

A redirect_uri that contains a username or password is rejected. If you are building an integration whose callback is on another host, contact Perspective to have it added.

The server forwards every other parameter to Auth0 and sets these itself:

Parameter set by serverValue
redirect_urihttps://api.perspective.co/oauth/callback — Auth0 only ever redirects to the server's callback, which relays the result to the client's own redirect_uri
stateAn opaque relay state that carries the client's redirect_uri and state
audienceAUTH0_AUDIENCE env var
connectionPerspective's email and password database (AUTH0_CONNECTION), or google-oauth2 for the choice page's Google button. A connection sent by the client is ignored

Response: one of

  • 200 text/html: the sign-in choice page. Its two buttons link to https://authenticate.perspective.co/authorize?<params>, identical except for connection. The page is not cached and can't be framed; open it in a browser window or popup.
  • 302 redirect to https://authenticate.perspective.co/authorize?<params> with the email and password database, where the choice page is not enabled.

Either way the client sees the same flow afterwards: the result comes back through /oauth/callback to its own redirect_uri.

Error response (400 application/json):

If redirect_uri is missing or not on the allowlist:

{
"error": "invalid_request",
"error_description": "redirect_uri is missing or not allowed"
}

Purpose: MCP clients discover this endpoint from the authorization_endpoint field in the authorization-server metadata. By routing through the Perspective API rather than pointing directly at Auth0, the server can inject the correct audience and connection values that clients do not know, and Auth0 only needs to know one callback URL.


GET /oauth/callback​

Receives the result of the Auth0 sign-in and relays it to the client. Clients never call this endpoint themselves: Auth0 redirects the user's browser here after sign-in, because /oauth/authorize set it as the redirect_uri.

Query parameters (set by Auth0):

ParameterDescription
stateThe relay state created by /oauth/authorize
codeThe authorization code, on success
error, error_descriptionThe OAuth error, on failure

Response: 302 redirect to the client's original redirect_uri, with the client's original state and either code or error (plus error_description when Auth0 sent one) added to its query string. If Auth0 sends both an error and a code, only the error is relayed and the code is discarded.

Error responses (400 application/json, error: "invalid_request"):

error_descriptionCause
missing stateNo state parameter
invalid statestate is not a relay state created by /oauth/authorize
redirect_uri not allowedThe client callback in the relay state is not on the allowlist

POST /oauth/token​

Proxies the OAuth2 token request to Auth0. MCP clients discover this endpoint from the token_endpoint field in the authorization-server metadata and use it both to exchange an authorization code and to refresh a token.

Request body (application/x-www-form-urlencoded or application/json):

The standard OAuth2 token parameters, forwarded to Auth0's /oauth/token as a form-encoded request. Fields given more than once, or that are not strings, are dropped.

GrantParameters
authorization_codegrant_type, code, code_verifier, client_id, redirect_uri
refresh_tokengrant_type, refresh_token, client_id

For an authorization_code grant the server replaces redirect_uri with its own callback, https://api.perspective.co/oauth/callback, because that is the redirect_uri Auth0 saw in the authorization request. A refresh_token grant is forwarded as sent.

Example request:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&code_verifier=<verifier>&client_id=<oauth-client-id>&redirect_uri=http://localhost:8080/callback

Response: Auth0's response, relayed with its status code. On success this is the standard OAuth2 token response (access_token, token_type, expires_in, and a refresh_token when the offline_access scope was requested). OAuth errors such as invalid_grant are relayed the same way.

Where the sign-in choice page is enabled, a sign-in that has no Perspective account behind it gets no token: the server answers 400 with invalid_grant and a message to show the user. This happens, for example, when someone continues with a Google account that never signed up for Perspective:

{
"error": "invalid_grant",
"error_description": "No Perspective account belongs to this login. If you use Perspective with email and password, sign in with those instead. New to Perspective? Sign up at https://start.perspective.co/en/mcp/signup, then connect again."
}

An account whose signup has no plan yet gets the same error with "Your Perspective account has no active plan yet. Finish your signup at https://start.perspective.co, then connect again." Such tokens would be rejected by every API call anyway.

If Auth0 cannot be reached within 30 seconds, the server answers 502:

{
"error": "server_error",
"error_description": "token endpoint unreachable"
}

POST /oauth/register​

Implements OAuth 2.0 Dynamic Client Registration. MCP clients that do not have a pre-registered client_id call this endpoint to obtain one.

Request body (application/json):

FieldRequiredDescription
redirect_urisYesNon-empty array of redirect URI strings

Response (201 application/json):

FieldValue
client_idThe shared OAuth client ID (from OAUTH_CLIENT_ID env var)
client_name"Perspective MCP Client"
redirect_urisThe redirect_uris array from the request, echoed back
grant_types["authorization_code", "refresh_token"]
response_types["code"]
token_endpoint_auth_method"none" — public client; no secret issued

Error response (400 application/json):

If redirect_uris is missing or not a non-empty array:

{ "error": "redirect_uris must be a non-empty array" }

Example request:

{
"redirect_uris": ["http://localhost:8080/callback"]
}

Example response:

{
"client_id": "<oauth-client-id>",
"client_name": "Perspective MCP Client",
"redirect_uris": ["http://localhost:8080/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none"
}
note

All dynamic registrations receive the same client_id. This is a single public client registration rather than per-client issuance. No client_secret is returned because the client is public (token_endpoint_auth_method: "none").


401 behavior on the MCP endpoint​

This is not itself an OAuth endpoint, but it is the entry point for the entire flow. When POST https://api.perspective.co/mcp receives a request with no token or an invalid token, it returns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.perspective.co/.well-known/oauth-protected-resource"

If a token was present but failed validation the header also includes:

WWW-Authenticate: Bearer resource_metadata="...", error="invalid_token", error_description="Invalid token"

The resource_metadata URL is what triggers the MCP client to begin the discovery and authorization flow described in OAuth Overview.


Summary​

MethodPathPurpose
GET/.well-known/oauth-protected-resourceProtected-resource metadata; entry point for client discovery
GET/.well-known/oauth-authorization-serverAuthorization-server metadata; lists all OAuth endpoints
GET/oauth/authorizeChecks the client's redirect_uri, then proxies the authorization redirect to Auth0, injecting audience + connection
GET/oauth/callbackReceives the Auth0 sign-in result and relays the code (or error) to the client's redirect_uri
POST/oauth/tokenProxies code exchange and token refresh to Auth0
POST/oauth/registerDynamic client registration; returns shared client_id