AuthKit Integration

FGA integrates with AuthKit to provide two layers of authorization. Organization-level roles and permissions are embedded directly in the session token for instant checks. Resource-scoped permissions are checked through the Authorization API.

When a user authenticates, their session token includes organization-level role information:

{
  sub: "user_01HXYZ..."
  org_id: "org_01HXYZ..."
  role: "org_member"
  permissions: ["org:view", "workspace:view", "project:view"]
}

Your application can check these permissions directly from the token without making API calls.

Why only organization-level roles?

Resource-scoped roles are intentionally excluded from the JWT:

• Token size – Users might have roles on hundreds of resources, bloating the JWT beyond practical limits
• Freshness – Resource assignments change frequently; stale tokens would cause mismatches
• Performance – Larger tokens mean slower requests and verification

For resource-level permissions, use the Authorization API – it’s fast and always current.

Organization layer (JWT) – Check the token directly for org-wide features like navigation and settings. Instant, no API call needed.

Resource layer (API) – Call the Authorization API for specific resource access. Checks the full permission hierarchy including inheritance.

Can this user edit this project?

1. Quick check: Does the JWT include project:edit for all projects?
   → If yes, authorized (no API call)

2. Otherwise: Call the API for this specific project
   → Checks direct assignments and inheritance

API checks reflect changes immediately.

JWT permissions require a session refresh since the token was issued at sign-in. Resource roles aren’t in the JWT, so API checks always return current data.