Skip to main content

API authentication

Module: insight (always on) | Role: Any member | Licence: Free+ | Auth: Session cookie or MCP OAuth 2.1

ev.energy supports two credentials:

  1. The signed-in session for the web app and the REST API. Sign in at https://eve.ev.energy; the browser sends the session cookie. A write also needs the X-CSRF-Token header and an Origin naming eve.ev.energy.
  2. MCP OAuth 2.1 + PKCE bearer tokens for AI clients on the Workspace MCP at https://eve.ev.energy/mcp, acting for a signed-in user.

Workspace API keys have been removed. OAuth with scoped keys for server-to-server access is planned.

The driver-facing Connect MCP (/connect/mcp) uses a separate ev.energy OAuth bearer scoped to the /connect surface. See Connect and connecting a client.

The signed-in session​

A request carrying the session cookie acts in your home workspace. A cookie request whose Origin names another site is refused with 403.

MCP OAuth 2.1 + PKCE​

For AI clients (Claude Code, Claude Desktop, Claude.ai, Cursor, etc.) use OAuth. There is no key to copy. Point the client at https://eve.ev.energy/mcp with no headers and the client runs the OAuth flow on first use:

  1. The client discovers the authorization server via GET /.well-known/oauth-authorization-server and the protected resource via GET /mcp/.well-known/oauth-protected-resource.
  2. The client calls GET /oauth/authorize with a PKCE code_challenge. S256 is required (the plain method is rejected).
  3. A browser opens the provider-selection page (/oauth/login); the user signs in with ev.energy, Google, or Microsoft SSO — the same login as the website.
  4. ev.energy returns a single-use authorization code (5-minute TTL) to the client's redirect URI.
  5. The client exchanges it at POST /oauth/token (with the PKCE code_verifier) for an access + refresh token pair.

You generally never construct the bearer header yourself — the client does. When present it looks like:

Authorization: Bearer <access_token> <!-- docs-public-safe: placeholder bearer token, not a real secret -->

OAuth (browser SSO) connections run as private conversation scope, so a user's personal / restricted agents are visible too.

Token lifetimes and refresh​

TokenLifetimeNotes
MCP access token60 minutes (configurable)Stateless JWT, type mcp_access.
MCP refresh token30 days (configurable)JWT + DB record, type mcp_refresh.

Refresh happens automatically: the client calls POST /oauth/token with grant_type=refresh_token. Token rotation applies — each refresh issues a new pair and atomically revokes the old refresh token (a replayed refresh fails). MCP tokens are distinct from web sessions and cannot be used interchangeably.

To revoke a token, the client calls POST /oauth/revoke (RFC 7009); it will re-OAuth on next use.

OAuth endpoints​

MethodPathPurpose
GET/.well-known/oauth-authorization-serverAuthorization server metadata (RFC 8414)
GET/mcp/.well-known/oauth-protected-resourceProtected resource metadata
POST/oauth/registerDynamic client registration (RFC 7591)
GET/oauth/authorizeStart the flow (redirects to /oauth/login)
GET/oauth/loginProvider selection page
POST/oauth/tokenExchange code or refresh token
POST/oauth/revokeRevoke a token (RFC 7009)

Scopes​

OAuth connections run as private conversation scope, so a user's personal and restricted agents are visible. A connection with no valid credential returns 401 and an empty MCP tool list (no tool names are leaked).

Rate limits​

Endpoints are rate-limited per IP, except the Gridbase API, which counts each workspace's requests together; exceeding a limit returns 429 Too Many Requests.

SurfaceDefault limit
Chat (POST /api/chat)10 requests/minute
Grid intelligence (/api/maps/grid-intelligence/...)60 requests/minute
Gridbase API (/api/gridbase/v1/...)100 requests/minute per workspace (per IP for a request with no workspace); can be raised per workspace on request
OAuth authorize30 requests/minute
OAuth token exchange60 requests/minute

These are configurable defaults — your deployment's effective limits may differ.

Error responses​

StatusMeaning
401 UnauthorizedMissing, invalid, or revoked credential.
403 ForbiddenAuthenticated but lacking the required module / scope.
429 Too Many RequestsRate limit exceeded.
503 Service UnavailableBackend (e.g. auth DB) temporarily unreachable — distinct from a 401 so valid credentials aren't mistaken for invalid ones.