Get Started

Tokens

Choose the correct token flow for interactive clients, CLI, MCP, and automation.

Interactive users

The Web app and general OAuth clients use Authorization Code with PKCE. The CLI's epismo login wraps browser, SSO-discovery, and email-code behavior; do not reproduce those implementation details unless you are building another first-party client.

The API exposes login-method discovery and OTP endpoints for supported first-party/manual flows:

POST /v1/login-options
POST /v1/otp-tokens
POST /oauth/token

In the OTP grant, request an OTP for the email address, collect the code out of band, then exchange the OTP ID and code at the token endpoint. OTP creation is rate limited. Never log the code or token response.

CLI and CI

POST /v1/cli/tokens issues CLI-compatible credentials for an authenticated caller. In normal use, prefer epismo token create, especially with --workspace-id, because it selects context and formats the result correctly for automation.

GET /v1/cli/tokens lists your issued CLI tokens (id, workspace, and timestamps — never the raw secret) and DELETE /v1/cli/tokens/:tokenId revokes one by id. Prefer epismo token list and epismo token revoke <token-id>, which wrap these directly.

An EPISMO_TOKEN carries its workspace context and overrides the CLI's saved workspace. Create separate tokens per environment, store them in a secret manager, verify them with whoami, and rotate them independently. If a token leaks, revoke it by id instead of waiting for it to expire.

MCP

POST /v1/mcp/tokens and POST /v1/mcp/tokens/refresh issue and rotate first-party MCP token pairs. General MCP clients should use OAuth discovery rather than calling these endpoints directly. The token pair is scoped for the epismo-mcp client and should not be reused as a generic API credential.

Storage rules

  • Keep refresh tokens more securely than short-lived access tokens.
  • Never put credentials in URLs, Playbook Definitions, Case inputs, Records, source control, analytics payloads, or support screenshots.
  • Replace a rotated refresh token atomically.
  • Revoke on disconnect or suspected compromise; do not keep retrying an invalid refresh token.
  • Bind automation to the intended workspace instead of relying on a developer machine's saved default.