Authentication

ezForge uses two separate auth systems:

Platform auth — authenticates you (the developer) to the ezForge API and CLI
MCP auth — authenticates MCP clients (AI assistants) to your deployed servers

Platform authentication

API keys

API keys are scoped, revocable credentials for programmatic access to the ezForge control plane. Create an API key in the dashboard under Project → API Keys, or via the CLI:

ezforge project create-key my-first-project --name "ci-deploy" --scopes "deployments:write,servers:read"

Keys use the prefix ezf_live_ (production) or ezf_test_ (test environment). Available scopes:

Scope	Description
`servers:read`	List and view servers
`servers:write`	Create, update, delete servers
`deployments:read`	View deployment history
`deployments:write`	Trigger deploys and rollbacks
`logs:read`	Stream server logs
`metrics:read`	View server metrics
`billing:read`	View billing and usage

Using an API key:

curl -H "Authorization: Bearer ezf_live_..." https://api.ezforge.ai/v1/projects

Session tokens

The ezForge CLI and dashboard use session-based auth (HTTP-only cookies, 1-hour expiry). Use ezforge auth login to authenticate the CLI.

MCP authentication

Every deployed MCP server is protected by OAuth 2.1 with mandatory PKCE (S256 code challenge method). This means MCP clients must complete an authorization flow before they can call your server’s tools.

ezforge_managed mode (default)

ezForge acts as the OAuth authorization server. No configuration needed — your server is protected out of the box. Client registration — two paths:

Path	When to use
CIMD (preferred)	Your client can host a metadata document at a stable HTTPS URL
DCR (fallback)	Your client cannot host a metadata document

CIMD (Client ID Metadata Document) — the MCP spec’s preferred path. Your client uses its own metadata URL as client_id. ezForge auto-fetches and registers the client on first authorization request. No separate registration call required. DCR (Dynamic Client Registration, RFC 7591) — POST metadata to /api/v1/servers/:id/clients or include clientMetadataUrl in the body for CIMD explicit pre-registration. MCP clients discover auth metadata via the standard .well-known endpoints:

GET https://app.ezforge.ai/.well-known/oauth-authorization-server

This returns RFC 8414 Authorization Server Metadata, including "client_registration_types_supported": ["automatic"], signalling CIMD support. MCP clients also discover protected resource metadata via:

GET https://{slug}.mcp.ezforge.ai/.well-known/oauth-protected-resource

Response:

{
  "resource": "https://my-server.mcp.ezforge.ai",
  "authorization_servers": ["https://app.ezforge.ai"],
  "scopes_supported": ["mcp:read", "mcp:write", "mcp:execute", "offline_access"],
  "bearer_methods_supported": ["header"]
}

BYOA mode (Bring Your Own Auth)

If you have an existing OAuth 2.1 authorization server, you can configure your server to accept tokens from it:

ezforge servers update my-server \
  --auth-mode byoa \
  --byoa-issuer https://auth.example.com \
  --byoa-jwks-uri https://auth.example.com/.well-known/jwks.json \
  --byoa-authorization-endpoint https://auth.example.com/oauth/authorize \
  --byoa-token-endpoint https://auth.example.com/oauth/token

ezForge performs a lightweight RFC 6750 structural Bearer-token check, then forwards the token to your MCP server for full JWT verification.

OAuth scopes

Scope	Description
`mcp:read`	List available tools
`mcp:write`	Call tools that modify state
`mcp:execute`	Execute arbitrary tool calls
`offline_access`	Request refresh tokens

Token lifetimes

Token type	Lifetime
Access token	15 minutes
Refresh token	30 days (rotated on use)
Auth code	10 minutes (single-use)

Getting Started

Concepts

Templates

Changelog

Platform authentication

API keys

Session tokens

MCP authentication

ezforge_managed mode (default)

BYOA mode (Bring Your Own Auth)

OAuth scopes

Token lifetimes

​Platform authentication

​API keys

​Session tokens

​MCP authentication

​ezforge_managed mode (default)

​BYOA mode (Bring Your Own Auth)

​OAuth scopes

​Token lifetimes

Platform authentication

API keys

Session tokens

MCP authentication

ezforge_managed mode (default)

BYOA mode (Bring Your Own Auth)

OAuth scopes

Token lifetimes