API authentication
Module:
insight(always on) | Role: Any member | Licence: Free+ | Auth: Session cookie or MCP OAuth 2.1
ev.energy supports two credentials:
- 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 theX-CSRF-Tokenheader and anOriginnamingeve.ev.energy. - 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:
- The client discovers the authorization server via
GET /.well-known/oauth-authorization-serverand the protected resource viaGET /mcp/.well-known/oauth-protected-resource. - The client calls
GET /oauth/authorizewith a PKCEcode_challenge. S256 is required (theplainmethod is rejected). - 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. - ev.energy returns a single-use authorization code (5-minute TTL) to the client's redirect URI.
- The client exchanges it at
POST /oauth/token(with the PKCEcode_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
| Token | Lifetime | Notes |
|---|---|---|
| MCP access token | 60 minutes (configurable) | Stateless JWT, type mcp_access. |
| MCP refresh token | 30 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
| Method | Path | Purpose |
|---|---|---|
| GET | /.well-known/oauth-authorization-server | Authorization server metadata (RFC 8414) |
| GET | /mcp/.well-known/oauth-protected-resource | Protected resource metadata |
| POST | /oauth/register | Dynamic client registration (RFC 7591) |
| GET | /oauth/authorize | Start the flow (redirects to /oauth/login) |
| GET | /oauth/login | Provider selection page |
| POST | /oauth/token | Exchange code or refresh token |
| POST | /oauth/revoke | Revoke 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.
| Surface | Default 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 authorize | 30 requests/minute |
| OAuth token exchange | 60 requests/minute |
These are configurable defaults — your deployment's effective limits may differ.
Error responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing, invalid, or revoked credential. |
403 Forbidden | Authenticated but lacking the required module / scope. |
429 Too Many Requests | Rate limit exceeded. |
503 Service Unavailable | Backend (e.g. auth DB) temporarily unreachable — distinct from a 401 so valid credentials aren't mistaken for invalid ones. |