> ## Documentation Index > Fetch the complete documentation index at: https://docs.alfiz.dev/llms.txt > Use this file to discover all available pages before exploring further. # Alfiz Cloud API Endpoints: The Complete REST Surface > Every Alfiz Cloud endpoint under /api/v1, grouped by area, with the gate and semantics of each, over the same server functions the Dashboard calls. All paths below are relative to the base `/api/v1`. Three gate notations recur: **Seat** (any admin seat or portal session), `alfiz_internal.*` keys (org-domain permissions, enforced by whichever provider currently holds the org root), and **Seat + `cloud.app:`** (a seat holding a grant scoped to that application). Org-domain gates use the built-in keys every Alfiz catalog carries: `alfiz_internal.access.{read, manage_grants, manage_revokes, manage_roles, manage_groups, manage_reporting, view_as}`, `alfiz_internal.requests.{read, decide_request}`, `alfiz_internal.audit.read`, and `alfiz_internal.catalog.{read, publish_catalog}`. Account gates are an admin seat, or the named `cloud.*` key, held globally or at `cloud.app:` for one application. ## Auth and orgs | Method | Path | Gate | What it does | | ------ | ---------------- | ------- | ---------------------------------------------------------- | | POST | `/auth/sign-in` | Public | Establish a session for `{org, userId}`. | | POST | `/auth/sign-out` | Session | End the session. | | GET | `/orgs` | Session | List orgs available to the caller, for the sign-in picker. | | POST | `/orgs` | Session | Create an org: `{id?, name, ownerUserId}`. | ## Publisher | Method | Path | Gate | What it does | | ------ | ------------------- | ------------- | -------------------------------------------------------------- | | POST | `/registry/publish` | Publisher key | Publish a namespace's catalog: `{document, expectedVersion?}`. | The `document` is the `CatalogDocument` from `catalog.toDocument()`. Publisher keys are namespace-scoped and valid for this endpoint only; sessions and admin keys cannot call it. Versions are monotonic per namespace; out-of-order publishes are rejected. See [the registry](/cloud/registry). ## Me | Method | Path | Gate | What it does | | ------ | --------------------- | ------------------------------- | ------------------------------------------------------- | | GET | `/orgs/{org}/me` | Seat | The caller's identity, seat, and effective permissions. | | POST | `/orgs/{org}/view-as` | `alfiz_internal.access.view_as` | Preview the org as another subject: `{viewAs}`. | A view-as preview only narrows. It can never show the viewer a surface their own grants would not reach. ## Org root Uniform across topologies: these gates are the `alfiz_internal.*` keys of the **current** org root. For a linked org the operation relays to your Application for enforcement; after federation, Alfiz Cloud enforces the same keys itself. | Method | Path | Gate | What it does | | ------------ | --------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | GET/POST | `/orgs/{org}/org/grants` | `alfiz_internal.access.read` / `alfiz_internal.access.manage_grants` | List or create org-domain grants. | | DELETE | `/orgs/{org}/org/grants/{id}` | `alfiz_internal.access.manage_grants` | Delete a grant. | | GET | `/orgs/{org}/org/grants/count` | `alfiz_internal.access.read` | Count grants matching a filter. | | GET/POST | `/orgs/{org}/org/revokes` | `alfiz_internal.access.read` / `alfiz_internal.access.manage_revokes` | List or create personal revokes. | | DELETE | `/orgs/{org}/org/revokes/{id}` | `alfiz_internal.access.manage_revokes` | Delete a revoke. | | GET/POST | `/orgs/{org}/org/roles` | `alfiz_internal.access.read` / `alfiz_internal.access.manage_roles` | List or create roles. | | PATCH/DELETE | `/orgs/{org}/org/roles/{id}` | `alfiz_internal.access.manage_roles` | Update or delete a role. | | GET/POST | `/orgs/{org}/org/groups` | `alfiz_internal.access.read` / `alfiz_internal.access.manage_groups` | List or create groups. | | PATCH/DELETE | `/orgs/{org}/org/groups/{id}` | `alfiz_internal.access.manage_groups` | Update or delete a group. | | PUT | `/orgs/{org}/org/groups/{id}/parents` | `alfiz_internal.access.manage_groups` | Set group parentage. A cycle is rejected with `ProviderWriteRejectedError`, `code: "graph_cycle"`, whose message names the full path. | | GET | `/orgs/{org}/org/groups/{id}/members` | `alfiz_internal.access.read` | List the users **directly** in this group. Membership through a child group is not expanded here, because that is the subject closure's job. | | POST | `/orgs/{org}/org/groups/{id}/dissolve` | `alfiz_internal.access.manage_groups` | Dissolve a virtual parent: its grants copy down to each child, then the children drift freely. | | GET | `/orgs/{org}/org/users` | `alfiz_internal.access.read` | List users. | | PUT | `/orgs/{org}/org/users/{id}/membership` | `alfiz_internal.access.manage_groups` | Set a user's group memberships. | | PUT | `/orgs/{org}/org/users/{id}/active` | `alfiz_internal.access.manage_grants` | Activate or deactivate a user. Deactivation is the reversible offboarding switch: an inactive principal evaluates to no access on every check shape. | | PUT | `/orgs/{org}/org/users/{id}/manager` | `alfiz_internal.access.manage_reporting` | Set the user's `reports-to` edge. | | GET | `/orgs/{org}/org/reporting-edges` | `alfiz_internal.access.read` | The full reporting hierarchy. | | GET | `/orgs/{org}/org/subject-access` | `alfiz_internal.access.read` | A subject's resolved access closure. | | GET | `/orgs/{org}/org/explain` | `alfiz_internal.access.read` | Explain a decision, showing which rows and paths produced it. | | DELETE | `/orgs/{org}/org/subjects/{subject}` | `alfiz_internal.access.manage_grants` | Remove all rows for a deleted subject. | | DELETE | `/orgs/{org}/org/scopes/{scope}` | `alfiz_internal.access.manage_grants` | Remove the rows at exactly this scope id, and cancel pending requests targeting it. Descendants are separate rows, so call it per deleted resource. | | GET | `/orgs/{org}/org/catalog` | Seat | The composed org catalog: what is grantable and requestable. | | GET | `/orgs/{org}/org/audit` | `alfiz_internal.audit.read` | The org-domain audit history. | | GET | `/orgs/{org}/org/epoch` | Seat | The current org epoch. | Instance-scoped rows live with their owner. Grant, revoke, and request writes at instance scopes belonging to a member application's namespace are routed to the owning Application by delegation, since the org root never holds another application's instance-scoped rows. ## Requests | Method | Path | Gate | What it does | | ------ | ---------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- | | GET | `/orgs/{org}/requests` | Seat (`mine=1`) or `alfiz_internal.requests.read` | List requests. `mine=1` is self-scoped and needs only a seat. | | POST | `/orgs/{org}/requests` | Seat | Submit a request. The requester is always the caller. | | GET | `/orgs/{org}/requests/queue` | Seat | The caller's approver queue. | | POST | `/orgs/{org}/requests/{id}/decide` | Provider-side `canDecide` + admin override | Decide: `{decision, note?, application?}`. | | POST | `/orgs/{org}/requests/{id}/cancel` | Requester | Cancel a pending request. | In a federated org the queue aggregates member-application queues, each entry tagged with its application. Pass `application` on decide when the entry names one. Decision entitlement resolves provider-side at decision time, with the admin override available to org administrators. ## Applications Per-application surfaces are **account surfaces**: they gate on a seat plus a grant scoped to `cloud.app:`, per [the uniform rule](/cloud/overview#the-uniform-authorization-rule). | Method | Path | Gate | What it does | | -------- | ------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/orgs/{org}/applications` | `cloud.applications.read` (admin seats always pass) | List applications visible to the caller. | | POST | `/orgs/{org}/applications` | `cloud.applications.register_application` | Register an application. | | GET | `/orgs/{org}/applications/{app}` | Seat + `cloud.app:` | Detail, including connection health and registry status. | | POST | `/orgs/{org}/applications/{app}/link` | Seat + `cloud.app:` | Link: `{relayUrl}`, the base URL your provider handler is mounted below; operations POST to `{relayUrl}/v1/{op}`. Returns the provider secret once. | | POST | `/orgs/{org}/applications/{app}/unlink` | Seat + `cloud.app:` | Remove the link registration. | | DELETE | `/orgs/{org}/applications/{app}` | `cloud.applications.delete` at `cloud.app:` | Delete the application entry. | | POST | `/orgs/{org}/applications/{app}/federate` | `cloud.applications.federate_application` at `cloud.app:` | Federate. The first federation is promotion. Body: `{resolutions?}` for merge conflicts. | | POST | `/orgs/{org}/applications/{app}/demote` | `cloud.applications.demote_application` at `cloud.app:` | Demote, available when this is the last member. | | POST | `/orgs/{org}/applications/{app}/audit-optin` | `cloud.retention.manage_retention` at `cloud.app:` | Toggle hosted audit retention: `{optIn}`. | | POST | `/orgs/{org}/applications/{app}/publish` | `cloud.applications.publish_catalog` at `cloud.app:` | Publish the catalog: `{document, expectedVersion?}`. | | POST | `/orgs/{org}/applications/{app}/ingest-audit` | `cloud.retention.manage_retention` at `cloud.app:` | Pull the Application's opted-in audit stream into hosted retention now. | | GET/POST | `/orgs/{org}/applications/{app}/grants` | Seat + `cloud.app:` | The application's scoped grants, served by delegation from the owner. | | DELETE | `/orgs/{org}/applications/{app}/grants/{id}` | Seat + `cloud.app:` | Delete a scoped grant. | | GET/POST | `/orgs/{org}/applications/{app}/revokes` | Seat + `cloud.app:` | The application's revokes. | | DELETE | `/orgs/{org}/applications/{app}/revokes/{id}` | Seat + `cloud.app:` | Delete a revoke. | | GET | `/orgs/{org}/applications/{app}/requests` | Seat + `cloud.app:` | The application's requests. | | GET | `/orgs/{org}/applications/{app}/audit` | Seat + `cloud.app:` | The application's audit history. | | GET | `/orgs/{org}/applications/{app}/catalog` | Seat + `cloud.app:` | The application's published catalog. | | GET | `/orgs/{org}/applications/{app}/ancestors?scope=` | Seat + `cloud.app:` | Resolve a scope's ancestor chain, for display. | Promotion via `federate` follows [the runbook](/cloud/promotion): export, validation, atomic flip, read-model push-down. `PromotionConflictError` (409) returns the `conflicts` array that `resolutions` answers. ## Registry | Method | Path | Gate | What it does | | ------ | --------------------------------------------- | --------------------- | ------------------------------------------------------------------------ | | GET | `/orgs/{org}/registry` | Seat | List published namespaces. | | GET | `/orgs/{org}/registry/{ns}` | Seat | Namespace detail: versions, tombstones, publisher. | | GET | `/orgs/{org}/registry/{ns}/document?version=` | Seat | Export the `CatalogDocument`, the input to `alfiz-verify codegen`. | | GET | `/orgs/{org}/registry/drift` | `cloud.registry.read` | The drift report: roles and grants referencing keys no longer published. | ## Seats and API keys | Method | Path | Gate | What it does | | ------------ | ---------------------------- | ------------------------------------------------ | -------------------------------------------------------- | | GET/POST | `/orgs/{org}/seats` | `cloud.seats.read` / `cloud.seats.invite_seat` | List or invite admin seats. | | PATCH/DELETE | `/orgs/{org}/seats/{userId}` | `cloud.seats.update_seat` / `cloud.seats.delete` | Update or remove a seat. | | GET/POST | `/orgs/{org}/api-keys` | `cloud.applications.manage_credentials` | List or create API keys: admin, principal, or publisher. | | DELETE | `/orgs/{org}/api-keys/{id}` | `cloud.applications.manage_credentials` | Revoke a key. | ## Billing | Method | Path | Gate | What it does | | ------ | -------------------------------------- | --------------------------- | ------------------------------------------------- | | GET | `/orgs/{org}/billing/usage` | `cloud.billing.read` | Every meter, exactly as the Dashboard renders it. | | PUT | `/orgs/{org}/billing/caps/{dimension}` | `cloud.billing.manage_caps` | Set a hard cap for one dimension. | Crossing a cap degrades hosted convenience only. See [Metering and caps](/cloud/metering). ## Retention | Method | Path | Gate | What it does | | ------ | ------------------------------ | ------------------------------ | ------------------------------------------------------------ | | GET | `/orgs/{org}/retention` | `cloud.retention.read` | Retained audit events, filterable by application and action. | | GET | `/orgs/{org}/retention/export` | `cloud.retention.export_audit` | Export retained audit events. | ## Sync | Method | Path | Gate | What it does | | ------ | ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------ | | POST | `/orgs/{org}/sync` | `cloud.applications.link_application` | Push the org read model down to federated members now, ahead of the regular cadence. |