Get Started

Tokens

Issue access tokens for CLI and MCP clients.

Beyond the standard OAuth flow, Epismo offers two product-specific token endpoints that return an access token directly: one for CLI use, and one for MCP clients. Use these when you want a token for a known client type without driving the full browser authorization flow.

You are building… Use
A client connecting through the CLI A CLI token
An MCP client connecting to Epismo An MCP token

CLI tokens

POST /v1/cli/tokens
Authorization: Bearer <token>
Content-Type: application/json
 
{ "workspaceId": "workspace-id" }

The response includes accessToken, refreshToken, tokenType, expiresIn, and scope. Use accessToken as the bearer token on subsequent requests.

If workspaceId is omitted, the token inherits the authorized request context. Pass an explicit workspace ID so the request context is reproducible and credit usage is attributed to the right workspace.

MCP tokens

Method Path Purpose
POST /v1/mcp/tokens Issue an MCP token
POST /v1/mcp/tokens/refresh Refresh an MCP token

MCP tokens authorize MCP clients that connect to the Epismo MCP server, and carry the mcp scope.

Issuing an MCP token requires a resource field whose value is the absolute http or https URL of the MCP server resource. Refreshing requires both refreshToken and the same resource URL.

{ "resource": "https://mcp.epismo.ai/", "workspaceId": "workspace-id" }

workspaceId is optional. Include it when the MCP client should operate in a specific workspace instead of personal space.

Token lifetime and security

  • Access tokens expire after the period given by expiresIn (seconds). Use the refreshToken to obtain a new access token instead of re-authenticating.
  • Treat any token like a password: store it as an encrypted secret, never commit it, and never print it in logs.
  • Issue a separate token per integration so you can revoke one without disrupting the others. Tokens can be revoked through /oauth/revoke.