Heplon

HTTP endpoints

Every /api/v1 and /mcp endpoint requires authentication: either an Authorization: Bearer <token> header (programmatic clients) or the opaque session cookie (browser).

Discovery

MethodPathAuthDescription
GET/.well-known/oauth-protected-resourceNoneOAuth 2.0 Protected Resource Metadata. Lets clients discover how to obtain a token.

Agent (MCP)

MethodPathAuthDescription
POST/mcpBearer tokenModel Context Protocol endpoint over Streamable HTTP.

Browser login

These drive the server-side login flow. They use the opaque session cookie, not a Bearer token.

MethodPathAuthDescription
GET/api/auth/loginNoneStarts the authorization-code + PKCE flow; redirects to Keycloak.
GET/api/auth/callbackNoneOAuth callback; exchanges the code, opens a session, and sets the session cookie.
GET/api/auth/meSession cookieReturns the authenticated identity (name, email, tenant).
POST/api/auth/logoutSession cookieInvalidates the session and clears the cookie.

Connectors (/api/v1/connectors)

MethodPathDescription
GET/api/v1/connectorsList the tenant's connectors (id, name, kind, URL; no secrets).
POST/api/v1/connectorsRegister a new connector. Returns 202 Accepted with connector_id and job_id.
PUT/api/v1/connectors/{id}Update a connector's name or URL. Omitting a secret field preserves the stored value.
DELETE/api/v1/connectors/{id}Remove a connector. Returns 204 No Content.
GET/api/v1/ingest-jobsList the tenant's ingest jobs.

Users and groups (/api/v1)

MethodPathDescription
GET/api/v1/usersList the tenant's users (id, display identity, group membership, status).
POST/api/v1/users/inviteInvite a user by email. Creates a pending principal; reconciled on first login.
GET/api/v1/groupsList the tenant's groups.
POST/api/v1/groupsCreate a group. Returns the group's stable id.
PATCH/api/v1/groups/{id}Rename a group. Grants and memberships follow the rename.
POST/api/v1/groups/{id}/membersAdd a user to a group. Idempotent.
DELETE/api/v1/groups/{id}/membersRemove a user from a group. No-op if the user is not a member.

Permissions (/api/v1)

MethodPathDescription
GET/api/v1/connectors/{id}/grantsList the grants on a connector (users and groups, roles, direct vs. inherited).
POST/api/v1/connectors/{id}/grantsGrant a role (owner, editor, or viewer) on a connector to a user or group. Idempotent.
DELETE/api/v1/connectors/{id}/grantsRevoke a grant. No-op if absent.
POST/api/v1/permissions/checkCheck whether a subject can perform an action on a connector, and return the grant path.

Provisioning policy (/api/v1)

MethodPathDescription
GET/api/v1/provisioning-policyRead the tenant's provisioning policy (JIT setting, default groups).
PUT/api/v1/provisioning-policyUpdate the provisioning policy. Requires the tenant's admin relation.

Graph (/api/v1)

MethodPathDescription
GET/api/v1/graphReturn the tenant's knowledge graph (nodes and edges).

Web app

MethodPathDescription
GET/ and any non-reserved pathServes the SPA's index.html so client-side routes resolve.