Authentication and access
Use identity, organization, member, role, and invitation resources as separate API concerns.
The API distinguishes a current authenticated person from an organization and from the access grants assigned to individual resources. Do not assume that a valid sign-in automatically grants a person access to a provider, plugin, configuration object, or worker.
A client needs both a valid credential and the correct organization plus resource grant. These are separate checks with different failure states.
- 01Authenticate
Send either the declared Bearer session or Den API key through a secure client boundary.
- 02Resolve identity
Read `/v1/me` and available organizations before selecting an organization-scoped action.
- 03Check resource grant
Read or update the matching resource access route with the narrowest valid role.
- 04Write or explain
Proceed with the requested action or render a specific unauthenticated, forbidden, or unavailable state.
Key endpoint groups
| Endpoint group | Purpose |
|---|---|
/v1/me | Read the current person and desktop configuration. |
/v1/me/orgs and /v1/org | Discover organization context and the active organization. |
/v1/members/*, /v1/roles/* | Manage people and role assignments. |
/v1/invitations and /v1/orgs/invitations/* | Create, preview, accept, and cancel invitations. |
| OAuth and OpenID discovery routes | Support registered authorization flows and client discovery. |
Access is a resource-level decision
Several resources expose an explicit access sub-route, for example:
/v1/config-objects/{configObjectId}/access
/v1/plugins/{pluginId}/access
/v1/llm-providers/{llmProviderId}/access/{accessId}
/v1/skill-hubs/{skillHubId}/access
Treat the resource and its access grants as separate lifecycle objects. The caller should first establish the organization context, then request or modify access using the narrowest available resource scope.
Safe client behavior
- Do not store bearer tokens or provider credentials in session artifacts or logs.
- Resolve the current person and organization before presenting organization-scoped actions.
- Display denied or missing access as a clear state, not as an empty resource list.
- Keep administrative actions behind an explicit role check in the calling application.
Status is part of the interaction model
| Outcome | Meaning | Good client response |
|---|---|---|
401 | The caller is not authenticated for the request | Ask for a fresh secure session or service credential. |
403 | The caller is known but lacks the required organization or resource grant | Show the resource scope and the next permitted owner action. |
404 | The route cannot resolve the requested object in the current context | Do not reveal unrelated resource metadata while trying alternative IDs. |
409 | The resource is in a conflicting lifecycle state | Re-read the object and show the actual state before asking the user to retry. |
Use OpenAPI and integration for credential selection and base URL behavior. Use the current OpenAPI operation for every route-specific authorization and error response.
Refer to packages/docs/openapi.json for authentication schemes, exact response shapes, and the API definition in the current revision.