Operator API

Let whoever runs a Renga deployment manage it from their own automation: create organizations and invite their owners, set limits and locked settings, manage deployment identity providers, suspend an organization, read usage, and move an organization in or out. Today an operator can do some of this only with release commands on the server, and some of it not at all.

The API is for operating a deployment, not for using it. Except for an explicitly authorized transfer, it never reads or changes an organization’s inventory. It never signs in as a person or returns a reusable application credential or user session; an authorized export may return the short-lived download capability defined below. Organization owners keep control of organization-owned configuration, such as their own identity providers. A token with transfer authority is consequently as sensitive as tenant-owner access, not an ordinary provisioning credential.

An operator token authenticates the API. It belongs to the deployment, not to an organization or a user.

Authentication checks the stored hash, expiry, revocation, and source address on every request through a credential path separate from user and agent authentication. The API requires HTTPS outside development. Source restrictions use the connection’s peer address unless the deployment explicitly names trusted reverse proxies; forwarding headers are accepted only from those proxies and are resolved with the same trusted-hop rules as the rest of the deployment.

Scopes keep a token to what its automation needs. A write scope includes the matching read operation needed to obtain versions and observe results:

Self-revocation requires authentication but no additional scope. Every other operation requires the scope named above; having one scope never implies an unrelated scope.

An operator sets an organization’s policy as one document, replacing it whole:

SCIM remains available under RFD 16's first-release rules rather than becoming entitlement-gated. If an entitlement disables an organization provider, Renga uses RFD 15's provider-disable behavior and completes RFD 16's source-bound membership and grant reductions before acknowledging the change. Ordinary RFD 19 security-setting changes keep RFD 19's own effective-time rules; they are not feature withdrawal and do not terminate running work.

Deployment-wide defaults for all three come from the environment, and an organization’s policy overrides them. A setting that neither locks stays the owners' choice.

The API exposes RFD 15's existing deployment-provider lifecycle; it does not create a second provider store or mutation contract. Stored configuration, encrypted secrets, immutable provider identity, authoritative revisions, fail-closed cache freshness, pending revisions, and purpose-bound test callbacks all follow RFD 15. Test and activation remain one atomic transition for the exact pending revision. Responses omit saved secrets entirely.

Environment providers remain read-only. They override a stored deployment provider only when RFD 15 permits the collision because all immutable properties match; every incompatible collision refuses boot. Ordinary API and release-command changes use RFD 15's serialized guard that preserves a usable deployment sign-in method. They add no per-user guarantee and preserve the distinction between sign-in, RFD 19's account re-check, and RFD 13 terminal step-up. RFD 15's recover-local escape hatch remains release-command-only and is never exposed to a bearer token. Organization providers are not reachable through this API; they belong to their organization’s owners.

The API reports each organization’s usage for capacity planning and internal cost allocation:

Daily totals are kept for 400 days.

Counters use UTC calendar days. Intake requests and bytes count accepted requests once after deduplication; jobs count a job once when created; terminal minutes are the sum of connected seconds rounded up only when the daily value is presented. Failed and retried attempts do not inflate totals. These are operational measurements, not billing records, until a later RFD defines a billing contract.

An operator sometimes needs to look inside an organization to diagnose a problem. Renga has no impersonation, and nothing in this API reads inventory or acts as a user, so that access is a grant the organization’s owners make, visible to them, and revocable by them at any moment. The operator’s part is to say who its support people are; it can never grant itself access.

These endpoints use RFD 20's archive and export/import engine, including its validation, principal mapping, historical-only jobs, pending security state, destination policy, and atomic import. The API can start, inspect, and cancel an export, then authorize a download. It can also create an empty organization and import an archive into it. This is the sole exception to the ordinary inventory boundary and requires transfers:write for every start, cancellation, download authorization, and import; transfers:read alone reveals only status and non-secret metadata.

An export omits passwords, session material, API and intake keys, provider and integration secrets, pending invitation secrets, and other credentials. A download authorization is a short-lived, single-use capability bound to the requesting token and is never returned in a status response. It is separate from RFD 20's owner-authorized seven-day artifact lifetime. Revoking the token or cancelling the transfer invalidates it. Import verifies and stages the archive before atomically checking that the destination is still empty and making its inventory visible. Security approvals return pending, imported users receive no access without an independently valid membership, and no credential from the source becomes usable in the destination.

Writes are safe to retry. Every create, invitation, transfer start, and other non-idempotent action requires an Idempotency-Key. Its namespace is the immutable token ID, HTTP method, and canonical route. Renga stores a digest of the normalized request and the completed response for at least 24 hours and returns the retention deadline. A retry with the same request returns the stored result; a different request in the same namespace returns 409. Concurrent requests serialize on the key, persist one operation before any side effect is queued, and converge on that operation and result.

Authentication and current scope authorization run before a stored result is returned, so expiry or revocation cannot be bypassed by replay. Retries of an asynchronous operation return the same operation ID. Cancellation, suspension, resume, and deletion scheduling also define the already-requested target state as success rather than repeating a side effect.

Policy and provider documents are replaced whole with PUT. They require If-Match with the version from the last read: a missing precondition returns 428, a stale one returns 412, and comparison and update happen atomically. Provider responses omit the client-secret field. Omitting it from a write preserves the current secret, an explicit replacement object changes it, and explicit null clears it only while the provider is disabled. A redacted read can therefore be written back without erasing a secret.

This lets automation hold the desired state and apply it repeatedly until the deployment matches.

Release commands call the same mutation functions and obey the same preconditions. For a non-idempotent action they accept or generate an operation key and print it, so rerunning a command can recover the same operation.

Deletion has distinct active, deletion_pending, and purging states. The purge worker locks and changes deletion_pending to purging only when the stored deadline has passed. Cancellation or resume locks the same record, so one of cancellation and purge wins atomically; once purging begins it cannot be cancelled.

Purge removes organization-owned inventory, settings, memberships, pending invitations, and transfer artifacts. It does not delete shared user accounts. Deployment audit records retain their immutable organization ID and display name snapshot under the deployment’s audit-retention policy, while the organization Activity disappears with the organization. Export capabilities expire no later than purge.

Every attempted mutation is recorded in a deployment audit log with an allowlisted, secret-free summary: immutable actor ID and display-name snapshot, operation, target IDs, request ID, time, outcome, and changed field names. It never stores request bodies or authorization headers, secrets, invitation or idempotency keys, archive contents, or download capabilities. A change to an organization is also recorded in that organization’s Activity with the same sanitized summary, attributed to the operator token’s immutable ID and name snapshot, so owners can see what their deployment changed and when.

A successful mutation and its audit event commit in one transaction, or the mutation commits with a durable transactional outbox record that must become the audit event before success is returned. Release commands have the same audit and Activity guarantees and use an explicit local-operator actor with a command invocation ID; they are not anonymous or exempt because no API token is involved.

Every API operation has a matching release command using the same domain function, validation, lockout prevention, idempotency, and auditing, so a deployment without network access to the API can be operated the same way. renga support enable|disable|status manage the support source (Support access); like the API, they never turn an organization’s support access on.

Implementation checklist