Alfiz Cloud API Endpoints: The Complete REST Surface

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:<id> (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:<id> 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.

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:<id>, per the uniform 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:<id>`	Detail, including connection health and registry status.
POST	`/orgs/{org}/applications/{app}/link`	Seat + `cloud.app:<id>`	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:<id>`	Remove the link registration.
DELETE	`/orgs/{org}/applications/{app}`	`cloud.applications.delete` at `cloud.app:<id>`	Delete the application entry.
POST	`/orgs/{org}/applications/{app}/federate`	`cloud.applications.federate_application` at `cloud.app:<id>`	Federate. The first federation is promotion. Body: `{resolutions?}` for merge conflicts.
POST	`/orgs/{org}/applications/{app}/demote`	`cloud.applications.demote_application` at `cloud.app:<id>`	Demote, available when this is the last member.
POST	`/orgs/{org}/applications/{app}/audit-optin`	`cloud.retention.manage_retention` at `cloud.app:<id>`	Toggle hosted audit retention: `{optIn}`.
POST	`/orgs/{org}/applications/{app}/publish`	`cloud.applications.publish_catalog` at `cloud.app:<id>`	Publish the catalog: `{document, expectedVersion?}`.
POST	`/orgs/{org}/applications/{app}/ingest-audit`	`cloud.retention.manage_retention` at `cloud.app:<id>`	Pull the Application’s opted-in audit stream into hosted retention now.
GET/POST	`/orgs/{org}/applications/{app}/grants`	Seat + `cloud.app:<id>`	The application’s scoped grants, served by delegation from the owner.
DELETE	`/orgs/{org}/applications/{app}/grants/{id}`	Seat + `cloud.app:<id>`	Delete a scoped grant.
GET/POST	`/orgs/{org}/applications/{app}/revokes`	Seat + `cloud.app:<id>`	The application’s revokes.
DELETE	`/orgs/{org}/applications/{app}/revokes/{id}`	Seat + `cloud.app:<id>`	Delete a revoke.
GET	`/orgs/{org}/applications/{app}/requests`	Seat + `cloud.app:<id>`	The application’s requests.
GET	`/orgs/{org}/applications/{app}/audit`	Seat + `cloud.app:<id>`	The application’s audit history.
GET	`/orgs/{org}/applications/{app}/catalog`	Seat + `cloud.app:<id>`	The application’s published catalog.
GET	`/orgs/{org}/applications/{app}/ancestors?scope=`	Seat + `cloud.app:<id>`	Resolve a scope’s ancestor chain, for display.

Promotion via federate follows the runbook: 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.

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.

Client API

Application

Catalog Definition

Static Verification

Alfiz Cloud API

Alfiz Cloud API Endpoints: The Complete REST Surface

Auth and orgs

Publisher

Me

Org root

Requests

Applications

Registry

Seats and API keys

Billing

Retention

Sync

​Auth and orgs

​Publisher

​Me

​Org root

​Requests

​Applications

​Registry

​Seats and API keys

​Billing

​Retention

​Sync

Auth and orgs

Publisher

Me

Org root

Requests

Applications

Registry

Seats and API keys

Billing

Retention

Sync