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.
Relationship to Policies
Section titled “Relationship to Policies”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 providers
Section titled “Authentication providers”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).
Admin endpoints
Section titled “Admin endpoints”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 |
Business rules
Section titled “Business rules”| 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.
Related Components
Section titled “Related Components”- 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