AeThex-OS/docs/ENTITLEMENTS_QUICKSTART.md

Entitlements Quickstart

This guide helps you set up the OS Kernel (identity + entitlements) and use the API to issue, verify, resolve, and revoke entitlements.

1) Run OS Kernel Migration

Ensure DATABASE_URL is set in your environment (Railway/Supabase Postgres). Then run the OS Kernel migration. You can do this either from the dev shell or the in-app Terminal (Admin only).

• Dev shell:
  • npx ts-node script/run-os-migration.ts
• In-app Terminal:
  • Command: migrate-os (now available in the command dropdown)

This creates tables:

• aethex_subjects, aethex_subject_identities
• aethex_issuers, aethex_issuer_keys
• aethex_entitlements, aethex_entitlement_events
• aethex_audit_log

2) Create an Issuer

Insert an issuer record with a public_key and optional metadata. You can use SQL or your DB console (Supabase) for now.

Example SQL:

INSERT INTO public.aethex_issuers (name, issuer_class, scopes, public_key, is_active)
VALUES ('AeThex Platform', 'platform', '["issue","revoke"]'::json, 'PUBLIC_KEY_STRING', true)
RETURNING id;

Save the returned id as your issuer_id.

3) Issue an Entitlement

Endpoint: POST /api/os/entitlements/issue

Headers:

• x-issuer-id: <issuer_id>

Body:

{
  "subject_id": "<optional: internal subject id>",
  "external_subject_ref": "roblox:12345", 
  "entitlement_type": "achievement",
  "scope": "project",
  "data": { "name": "Alpha Access" },
  "expires_at": null
}

Response:

{
  "success": true,
  "entitlement": {
    "id": "...",
    "type": "achievement",
    "scope": "project",
    "created_at": "..."
  }
}

4) Verify an Entitlement

Endpoint: POST /api/os/entitlements/verify

Body:

{ "entitlement_id": "..." }

Response (valid):

{
  "valid": true,
  "entitlement": {
    "id": "...",
    "type": "achievement",
    "scope": "project",
    "data": { "name": "Alpha Access" },
    "issuer": { "id": "...", "name": "AeThex Platform", "class": "platform" },
    "issued_at": "...",
    "expires_at": null
  }
}

Response (revoked/expired):

{ "valid": false, "reason": "revoked|expired", ... }

5) Resolve Entitlements (by subject or external ref)

Endpoint: GET /api/os/entitlements/resolve

Query params (choose one path):

• ?subject_id=<internal_subject_id>
• ?platform=roblox&id=12345

Response:

{
  "entitlements": [
    {
      "id": "...",
      "type": "achievement",
      "scope": "project",
      "data": { "name": "Alpha Access" },
      "issuer": { "name": "AeThex Platform", "class": "platform" },
      "issued_at": "...",
      "expires_at": null
    }
  ]
}

6) Revoke an Entitlement

Endpoint: POST /api/os/entitlements/revoke

Headers:

• x-issuer-id: <issuer_id>

Body:

{ "entitlement_id": "...", "reason": "Fraudulent use" }

Response:

{ "success": true, "message": "Entitlement revoked" }

Notes

• All OS routes are protected by the capability guard and expect authenticated context where relevant.
• Use Supabase console to inspect tables and audit logs.
• For production, plan issuer key rotation via aethex_issuer_keys; rotation endpoints can be added similarly.

Bot Integration Env (for external bots)

Add these to your bot repo (not the OS) so it can call the OS API:

• AETHEX_API_BASE=https://<your-os-host>
• AETHEX_ISSUER_ID=<issuer_id from step 2>
• AETHEX_REALM=foundation (optional; foundation already has required capabilities)