Skip to content

Authentication

Two modes, one endpoint. Both end at the same place: your credential is forwarded to the FolioX backend on every tool call, and the backend applies the same tenant scoping, roles, and scopes it applies to the FolioX app. The MCP server holds no authorization logic of its own.

OAuth (interactive)

The default for humans using claude.ai, Claude Desktop, Claude Code, Cursor, and other interactive clients.

  • Clicking Connect starts a standard OAuth flow against FolioX's identity provider. Log in with your FolioX account and pick your organization when prompted — the organization determines which customer's data you see.
  • You act as yourself: your role (Customer Admin, Dispatcher, …) governs what the tools can do.
  • Tokens refresh automatically; disconnecting the connector revokes the session.

API keys (machine)

For headless agents, backend services, and scheduled jobs.

  • Use your existing FolioX customer API key — the same keys that work against the FolioX REST API. Manage them in the FolioX app (generate, rename, rotate, revoke; optional IP allowlists and scopes apply).
  • Send it as a standard bearer token:
Authorization: Bearer <your-foliox-api-key>
  • The key is validated against the backend and then forwarded per request — revoking a key in FolioX cuts off MCP access within minutes at most, and every individual tool call is re-authorized by the backend regardless.

API keys cover the full tool surface

Keys with the right scopes can use every tool — reads, validation, creation, and the mutation verbs. Machine actions are attributed first-class in the audit history (actor type api_key plus the key's prefix), so the timeline always shows which key acted. Scopes follow the FolioX catalog (write:loads for dispatch writes, read:tanks, read:recommendations, read:drivers, read:allocations).

One credential only

Requests must carry exactly one credential. If both an Authorization bearer and an X-API-Key header arrive, the request is rejected with AUTH_AMBIGUOUS rather than silently picking one — ambiguous identity is treated as a caller bug, not a preference.

Tenancy and safety guarantees

  • Every id you can read, you can echo back; every id outside your tenant returns REF_NOT_FOUND — the backend's existence oracle doesn't reveal whether a foreign id exists.
  • The MCP server never mints, stores, or caches credentials of its own beyond short-lived validation state; the backend remains the single authority.
  • Organization access is provisioned by FolioX. If your login completes but tools return "missing the customer claim", your account isn't linked to an organization yet — contact your FolioX administrator.