Service API Reference

The orbit-service management API runs on port 3001. The introspect hot path runs separately on port 3000. All management endpoints require a tenant-scoped session token via Authorization: Bearer <token> unless noted.

Introspect (Port 3000)

The hot-path endpoint for real-time authorization checks. Authenticated with an API key, not a session token.

{
  "authenticated": true,
  "user": { "id": "...", "email": "...", "name": "...", "tenant_id": "..." },
  "granted": true,           // present if "permission" was requested
  "grants": { "perm": true },// present if "permissions" batch was requested
  "permissions": ["..."],    // present if include contains "permissions"
  "roles": ["..."],          // present if include contains "roles"
  "feature_flags": { "flag": true } // present if include contains "flags"
}

curl -X POST https://orbit.example.com/check \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "user-session-token",
    "tenant_id": "tenant-uuid",
    "permission": "documents.edit",
    "resource": { "owner_id": "user-123" }
  }'

Authentication

# Step 1: Login (no tenant_id → pre-tenant session)
curl -X POST https://orbit.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "admin@example.com", "password": "secret" }'
# → { "token": "pre-token", "expires_at": "...", "next": "tenant_select" }

# Step 2: List memberships
curl https://orbit.example.com/auth/memberships \
  -H "Authorization: Bearer ${PRE_TOKEN}"
# → { "data": [{ "tenant_id": "...", "tenant_slug": "acme", "tenant_name": "Acme Corp", "roles": ["admin"] }] }

# Step 3: Exchange for tenant-scoped session
curl -X POST https://orbit.example.com/auth/session/exchange \
  -H "Authorization: Bearer ${PRE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_slug": "acme" }'
# → { "token": "tenant-scoped-token", "expires_at": "...", "next": "complete" }

Tenants

All routes require a tenant-scoped session. Tenant isolation is absolute — you can only access your own tenant's data.

Users

User Roles

User Direct Permissions

Roles

Role Permissions

Permissions

Permissions are global (not tenant-scoped). Creating permissions requires the system tenant.

Modules

Modules group permissions (e.g. users, roles, oauth2).

Policies

Policies add runtime conditions to permission checks. When a permission has attached policies, the introspect endpoint evaluates each policy handler. AND logic: all must pass.

Policy Attachment

Built-in Policy Types

API Keys

API keys authenticate consuming applications against the introspect endpoint. The raw key is returned once at creation and stored as a SHA-256 hash.

Audit Logs

Every mutation is recorded. Logs capture old/new values, the acting user, IP address, and timestamp.

Feature Flags

Flags are defined globally and can be overridden per-tenant. Effective value = tenant override > global default.

Global Flags (System Tenant)

Tenant Flags

OAuth2 Clients

OAuth2 client management is proxied through orbit-service to orbit-oauth2's internal API. All mutations are audit-logged. Clients created here are tenant-owned: only your tenant can see or mutate them, and POST accepts an optional environment string that gets stamped into the client's issued tokens as the env claim. Clients with a third-party consent_uri/consent_jwk aren't creatable here yet — see POST /oauth2/register.

Signing Keys (System Tenant)

Domains

Domain inventory, CNAME ownership verification, and TLS expiry monitoring. A domain must be verified before a certificate can be requested for it.

Issuers

An issuer is either an acme directory (Let's Encrypt or any RFC 8555 CA) or an internal-ca self-signed root for private/internal domains. Secret material (ACME account key, EAB HMAC) is referenced by secret_id, never accepted or returned inline. An internal-ca issuer may bring its own root (ca_certificate_pem + ca_private_key_pem, P-256 ECDSA only) or self-generate one.

Certificates

Certificate orders are created and read through their owning domain. Issuance runs asynchronously on the job worker: POST enqueues certificate.issue and returns 202 immediately; poll the order or list endpoint for status to reach valid or failed. certificate_pem/chain_pem are public once issued; the leaf private key is never returned, only a reference to its secret id. A separate tenant-wide roll-up endpoint lists orders across every domain at once — order-level history (which issuer signed what, failed orders anywhere in the fleet), complementing the per-domain expiry snapshot at GET /domains.

Jobs

Read-only visibility into the cert-module job queue: domain.verify, domain.probe-expiry, and certificate.issue (renewals reuse the same type — there is no separate renewal job type). This is the only place a job that failed before a certificate_orders row existed, or one sitting in retry backoff, is visible at all.

Secrets

Encrypted key/value storage, scoped by tenant and optionally by environment. Session (dashboard) endpoints never return plaintext, only ciphertext metadata (version, key version, active flag) — the only place plaintext is ever decrypted is POST /tenants/:id/secrets/lease, a separate JWT-authed endpoint for machine clients (no session token, no dashboard route). A secret only becomes leasable once escrow_enabled is set via the escrow endpoint; cert-module private keys (leaf keys, ACME account keys, internal-CA root keys) are created with escrow off. POST .../rotate and PUT .../values both write a new version, but differ in whether a value must already exist: PUT requires the environment to be new (422 otherwise, meaning "use rotate"); POST rotate works whether or not one exists, deactivating the prior active version for that environment.