Orbit Service

The authorization backbone. Orbit Service handles everything from user management and role-based access control to real-time permission evaluation. Every authorization decision in your application flows through a single introspect endpoint — one query, sub-millisecond resolution, always consistent.

Key Capabilities

Role-Based Access Control

Assign permissions to roles, roles to users. Per-tenant isolation ensures one tenant's roles never leak into another.

Direct Permissions

Grant or explicitly deny individual permissions per-user. Time-bound access via expires_at. Explicit denies override any role-based grant.

Hierarchical Multi-Tenancy

Create child tenants under any tenant. Each child is fully isolated with its own users, roles, and permissions. The creator is automatically mirrored as owner.

Runtime Policy Engine

Attach policies to permissions for context-aware evaluation: ownership checks, department matching, resource state, business hours. AND logic; first failure short-circuits.

Two-Binary Architecture

Orbit Service runs as two separate processes sharing a single PostgreSQL database:

orbit-introspect (:3000)
The hot path. A single POST /check endpoint that consuming applications call on every authorization decision. Resolves session → user → roles → permissions → direct overrides → policies in one CTE query. Isolated connection pool prevents management traffic from competing for resources.
orbit-service (:3001)
The control plane. All management endpoints: authentication, user/role/permission CRUD, tenant management, API keys, audit logs, feature flags, and OAuth2 client management (proxied to orbit-oauth2).

Authentication Model

  • Session tokens — opaque tokens stored as SHA-256 hashes. Required for all management endpoints. Support pre-tenant and tenant-scoped sessions.
  • API keys — scoped per-tenant keys for machine-to-machine calls. Used exclusively on the introspect endpoint.
  • JWT access tokens — ES512-signed tokens issued by orbit-oauth2. The introspect endpoint resolves the JWT sub claim directly as a user ID, bypassing sessions entirely.

Audit & Compliance

Every mutation writes to the audit_logs table within the same database transaction. Logs capture the user, action, model type, old/new values, and IP address. Queryable by action, user, time range, and model type.

Seeded Modules

The setup script provisions 10 modules with 40+ permissions, covering all platform resources: tenants, users, roles, permissions, policies, audit, api-keys, feature-flags, modules, oauth2.

API Reference →