OAuth

Authorize public clients, obtain offline access, and discover server capabilities safely.

Treat discovery metadata as the source of truth for endpoint URLs, supported grants, scopes, response types, PKCE methods, and token authentication methods.

GET /.well-known/oauth-authorization-server
GET /.well-known/openid-configuration

Browser and installed clients

Public clients use Authorization Code with PKCE S256. Generate a fresh high-entropy code_verifier, send its S256 challenge during authorization, validate state on return, then exchange the code at the discovered token endpoint. Never use a client secret in software that cannot keep it confidential.

Use dynamic client registration when the client is not pre-registered. Register exact redirect URIs and reject redirects that do not match. Request the minimum scopes: read for reads, write for mutations, mcp for the MCP server, and offline_access only when the client must refresh without the user present.

OpenID Connect

Use the discovered userinfo endpoint when the client needs the authenticated profile. Do not infer identity or workspace authorization from an email address. Access tokens authorize API calls; ID and userinfo data identify the signed-in user according to the OpenID Connect contract.

Token lifecycle endpoints

The authorization server supports token issuance and refresh, userinfo, revocation, introspection, dynamic registration, and authorization-server metadata under /oauth/* and /.well-known/*. Refresh tokens rotate; replace the stored refresh token after every successful refresh and treat reuse or an invalid refresh response as a reason to reauthorize.

Revoke credentials when a user disconnects the integration. Introspection is for trusted server-side validation where appropriate; public clients should not expose credentials to another party merely to inspect them.

MCP authorization

MCP clients begin from the protected-resource metadata published by https://mcp.epismo.ai/, then follow its authorization-server reference and request mcp. The MCP resource server and API authorization server are separate origins, so honor the discovered audience and resource metadata rather than assuming one URL.