Reference
API and keys
Which token to use for sessions, MCP and log ingestion, with endpoint, lifecycle and error examples.
Last updated
On this page
Escanor's dashboard HTTP base is https://api.escanor.in/api/v1. MCP and OIDC have their own addresses. Each kind of key works only for its own purpose, as listed below.
Credential types
| Credential | Used for | Important limit |
|---|---|---|
| User session access token | Dashboard/app HTTP routes | Expires and is renewed by the application's refresh flow. |
| MCP key | Remote MCP integration tools | Does not replace a dashboard sign-in. |
| OIDC access token | Its granted scopes and resource audience | Do not use an ID token as an API credential. |
| Log ingest token | /observability/ingest | Submission only; cannot read logs or sign in. |
| Provider API key/token | The corresponding integration connection | Not an Escanor session token. |
Manage MCP connections under MCP or Settings > Developer > API and MCP keys. Escanor shows a new token only once. Give each client a distinct name. Rotation replaces the token immediately; update that client deliberately. Revocation stops that key, without deleting the connected provider's resources.
Dashboard requests
Dashboard routes authenticate a user session. The app sends workspace/organization context headers for compatibility. Project routes derive the workspace from the authenticated user; these headers do not switch workspaces or authorize another workspace. Session context selection currently has single-workspace behavior.
curl -fsS https://api.escanor.in/api/v1/auth/session \
-H 'Authorization: Bearer YOUR_SESSION_ACCESS_TOKEN'It returns session/bootstrap information for that user. Treat it as private account data. Do not copy real access or refresh tokens from storage into public examples. Prefer the application's supported session client instead of writing a new refresh loop.
curl -fsS 'https://api.escanor.in/api/v1/projects?search=example' \
-H 'Authorization: Bearer YOUR_SESSION_ACCESS_TOKEN' \
-H 'X-Workspace-Id: YOUR_WORKSPACE_ID' \
-H 'X-Organization-Id: YOUR_ORGANIZATION_ID'The context headers are for client compatibility and do not authorize anything on their own. See Projects for provider restrictions.
Public endpoint map
| Surface | Examples | Authentication |
|---|---|---|
| Sessions | /auth/session, /auth/sessions | User session |
| Projects | /projects, /projects/{id}/deployments | User session + workspace |
| Operations | /deployments, /incidents, /autopilot/runs | User session + role/policy |
| MCP setup | /agent/mcp/config, /agent/mcp/connections | User session |
| MCP install | POST /agent/mcp/install with {"name":"Example client"} | User session; returns token/config once |
| Log ingest | POST /observability/ingest | Dedicated ingest token |
| OIDC discovery | https://api.escanor.in/.well-known/openid-configuration | Public |
| MCP resource metadata | https://mcp.escanor.in/.well-known/oauth-protected-resource | Public |
This page does not promise versioned stability for every dashboard endpoint. Check response shapes and errors; provider-specific operations differ. Use OIDC for third-party authentication and MCP for integration automation.
Session and key lifecycle
GET /auth/sessions returns session IDs and creation/expiry/current-session metadata. DELETE /auth/sessions/{session_id} ends a selected session; POST /auth/sessions/revoke-others ends others. These routes require the user session and cannot be used with an ingest key.
For MCP, POST /agent/mcp/connections/{token_id}/rotate returns a replacement configuration; DELETE /tokens/{token_id} revokes it. Copy the new value only to that client and remove old credentials from its configuration. Keep credentials in a secret store/environment configuration, not prompts or version control.
Errors and retry behavior
| Status/result | Recovery |
|---|---|
401 | Check credential type, expiry and revocation. Sign in/refresh using the appropriate flow. |
403 | Check role, scope, audience and provider access; do not retry with broader privileges blindly. |
404 | Verify route/resource identifier and whether it is visible to this account. |
422 | Read validation field details and correct the body/query. |
429 | Respect Retry-After when provided and reduce frequency. |
5xx or network error | Retry reads with backoff; inspect the target before retrying a write. |
HTTP 200 with success:false or a tool error | Treat as failure; do not infer success from HTTP status alone. |
Limits vary by endpoint and plan. Never store credentials in example output. Related: Log ingestion, Permissions, Accounts and sessions.
Need help? Contact support with a redacted error and the affected version.