Get Started

OAuth

How Epismo issues and manages access tokens for API and MCP clients.

Epismo uses standard OAuth 2.0 with OpenID Connect to authenticate applications. If you are building a product integration, you will obtain an access token through this flow and then send it as a bearer token on every API request. Most users never call these endpoints directly (the CLI and supported MCP clients handle the flow for you), but they are documented here for teams building their own integration.

How the flow works

  1. Discover endpoints. Fetch the well-known metadata documents below instead of hard-coding URLs. They list the authorization, token, and user-info endpoints and the supported capabilities.
  2. Register a client. Use POST /oauth/register for dynamic client registration. Registered clients support the authorization_code and refresh_token grants by default.
  3. Authorize the user. Run the authorization-code flow (PKCE is supported) to obtain an authorization code.
  4. Exchange for tokens. Call POST /oauth/token to exchange the authorization code for an access token and a refresh token.
  5. Refresh as needed. When the access token expires, exchange the refresh token at POST /oauth/token with grant_type=refresh_token rather than sending the user through sign-in again.

The access token you receive is what authorizes your API calls. See Authentication for how to send it, and Tokens for the CLI- and MCP-specific token endpoints.

Endpoints

Method Path Purpose
POST /oauth/token Exchange an authorization code or refresh token for tokens
GET/POST /oauth/userinfo OpenID Connect user info for the current token
POST /oauth/register Dynamic client registration
POST /oauth/revoke Revoke an access or refresh token
POST /oauth/introspect Check whether a token is active and inspect its scopes
GET /.well-known/oauth-authorization-server Authorization server metadata (endpoints and capabilities)
GET /.well-known/openid-configuration OpenID Connect provider metadata

Scopes

Tokens carry scopes that determine what they can do. Read endpoints require read scopes and mutation endpoints require write scopes; MCP clients additionally need the mcp scope. Request only the scopes your integration needs.

MCP clients

MCP clients use the same OAuth model, but discover metadata through the MCP server's own well-known endpoints. See MCP setup for that flow.