Documentation
Public API & Discovery
Machine-readable and public-facing discovery resources exposed by ClearAccess.
Public API & Discovery
ClearAccess publishes a small public discovery surface for agents, integrators, and operational tooling.
Public endpoints
| Endpoint | Purpose |
|---|---|
/api/health |
Health and status check for the public application |
/.well-known/api-catalog |
Machine-readable API discovery catalog |
/.well-known/agent-skills/index.json |
Agent skills discovery index |
/.well-known/openid-configuration |
OIDC discovery metadata for agent authentication |
/.well-known/oauth-authorization-server |
OAuth authorization server metadata |
/.well-known/oauth-protected-resource |
OAuth protected resource metadata for /api |
/.well-known/mcp/server-card.json |
MCP server card for agent discovery |
/docs/api |
Human-readable overview of the public API surface |
Authentication surface
ClearAccess serves browser-oriented authentication routes under /api/auth/* through Better Auth.
- These routes support the product's existing session-based auth flows.
- OAuth/OIDC discovery metadata is published for agents that need to discover the current auth surface.
- Protected API metadata advertises the API resource identifier, authorization server, bearer-token method, and supported API token scopes.
- Personal API tokens can be issued from
/dashboard/account/api-tokensafter sign-in.
Agent-readable responses
Public HTML pages can be negotiated as markdown by sending:
Accept: text/markdown
When that header is used on eligible public pages, ClearAccess returns a markdown response with Content-Type: text/markdown.
What the API catalog advertises
The API catalog currently points to resources that are stable and publicly useful:
- the public API documentation
- the application health endpoint
- agent skills discovery metadata
- OAuth protected resource metadata
- MCP server-card metadata
The catalog does not claim an OpenAPI document in this phase, because that resource is not yet formally published.