Tenant, auth and RBAC

An organization is the tenant boundary. Users become members through an organization membership record, and every tenant-owned model carries organizationId. The API derives the active organization from the authenticated session after a membership check. A path, query parameter or JSON field can identify a resource, but it cannot select a different organization.

Authentication path

1. POST /api/v1/auth/register creates a user, an organization in REGISTERED, and an OWNER membership. The default trial is 14 days.
2. Email verification changes the organization to EMAIL_VERIFIED.
3. POST /api/v1/auth/login creates a session, returns a short-lived access token and rotates a refresh token family. The web flow also receives a CSRF token.
4. Each request resolves the membership and role again before permission checks. Sessions contain device, browser and IP metadata and can be revoked.
5. A refresh-token reuse attempt revokes the whole token family. API keys are hashed, prefixed dfk_, scoped and shown in plaintext only at creation.

Access JWTs are short-lived (15 minutes), use the api.devopsify.net issuer, and carry sub, orgId, role and scoped permissions. Cookie-authenticated mutations require the double-submit CSRF token. Production cookies must be HTTP-only, SameSite=Lax and Secure.

Role and permission evaluation

Roles are OWNER, ADMIN, OPERATOR and VIEWER. Roles map to granular permission rows rather than hardcoded checks in business logic. A mutation is admitted in this order:

authenticate -> resolve membership -> permission check
             -> entitlement check -> deterministic policy check
             -> approval / confirmation check -> persist intent

Layer	Example	Failure is recorded as
Permission	provisioning.apply	authorization error
Entitlement	cloud.live, ai.execute	ENTITLEMENT_MISSING
Policy	deny public admin ingress or an unapproved region	policy decision with reasons
Approval	risk 2 or 3 operation	pending or rejected approval

Changing organization context, role or entitlement in the browser cannot bypass any layer. Cross-tenant reads are treated as a critical defect and are covered by isolation tests.

Organization lifecycle

REGISTERED -> EMAIL_VERIFIED -> DEMO -> REVIEW_PENDING -> APPROVED -> ACTIVE is the normal path. REJECTED, SUSPENDED and EXPIRED are administrative or terminal states. A demo organization is deliberately constrained: mock provider mode only, preview-only provisioning, read-only/preview AI, simulated outbound webhooks and deterministic resettable data.

Platform administration is separate from organization ownership. It requires the explicit platform.admin entitlement and is used for activation review, status changes, entitlement limits and health checks. An organization OWNER is not automatically a platform administrator.