Skip to content

Subjects

Subjects represent who can access data in Alien Giraffe. This page covers the real authentication providers, the role model, and the admin user-management endpoints — not a generic identity-provider framework.

Every request is tied to the authenticated identity that created it, and every approval is tied to the identity that approved it. Policies reference this identity implicitly: there’s no separate “subjects” field to fill in — the platform already knows who’s asking because they’re logged in.

Authentication is selected with the [auth] section of a10e.toml (or the AUTH_PROVIDER environment variable), and is one of three real providers:

Provider How it works
local Local username/password auth, useful for development and the standalone bundle’s first-run setup. Configured with jwt_secret.
auth0 Auth0-issued JWTs are validated against auth0_domain / auth0_audience. On first login, a user record is created with the default user role, and the profile (email, name, avatar) is synced from Auth0’s /userinfo endpoint. auth0_bypass exists for local/dev use only.
workos WorkOS AuthKit access tokens are validated via WorkOS’s JWKS endpoint (WORKOS_JWKS_URL, WORKOS_CLIENT_ID, WORKOS_ISSUER, WORKOS_AUDIENCE). WorkOS resolves the caller’s organization (org_id claim) and role; WORKOS_ROLE_MAP maps WorkOS role slugs to Alien Giraffe roles, and WORKOS_DEFAULT_ROLE applies when no mapping matches.

If your organization already uses an enterprise identity provider (Okta, Azure AD, Google Workspace, etc.), configure it as a connection inside WorkOS AuthKit — Alien Giraffe itself only talks to WorkOS’s API and JWKS endpoint, it does not implement per-IdP integrations directly.

Every login issues a session backed by a JWT signed with jwt_secret. There is no separate session-duration or MFA configuration in the platform today; session lifetime follows the [expiry] settings in a10e.toml.

Three hierarchical roles, from least to most privileged:

super_admin
│
▼
admin
│
▼
user
Role Description
user Standard user. Default role for new accounts. Can create requests and use approved ones.
admin Can manage users and review/approve requests, in addition to everything a user can do.
super_admin Full control over all users and roles, including promoting/demoting other admins.

Access to this document’s data now generally happens inside an organization: organization_members.role carries the role for that org, and users.is_platform_admin marks accounts that can act across every organization (a small overlay on top of the role table above, used for cross-tenant administration).

All /v1/admin/users/* endpoints require admin or super_admin:

Endpoint Method Description
/v1/admin/users GET List all users (paginated)
/v1/admin/users/:id GET Get user details
/v1/admin/users/:id PATCH Update user
/v1/admin/users/:id DELETE Soft delete user
/v1/admin/users/:id/activate POST Activate user
/v1/admin/users/:id/deactivate POST Deactivate user
Action Who can perform it
Promote a user to admin or super_admin super_admin only
Demote an admin to user admin or super_admin
Demote a super_admin to any other role super_admin only
Modify your own role Nobody — self-modification is always blocked
Deactivate a user or admin account admin or super_admin
Deactivate a super_admin account super_admin only
Deactivate or delete your own account Nobody — self-action is always blocked
Delete a user admin or super_admin (soft delete — sets deleted_at, record is preserved)

Deactivated users (is_active = false) cannot authenticate; the auth middleware rejects them with 403 Forbidden until an admin reactivates the account.

See Users And Roles for the full endpoint reference and worked examples.

  • Policies — how identity combines with the other four components
  • Resources — what an authenticated subject can request access to
  • Constraints — the approval step a subject’s request goes through
  • Channels — how a subject reaches approved data
  • Context — the justification a subject must provide with every request