---
title: "adonia-roles API"
image: "https://adonia.pages.dev/og.png"
version: "next"
---

> Documentation Index
> Fetch the complete documentation index at: https://adonia.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# adonia-roles API

<!-- Generated by docs/site/scripts/generate_api.ts. Do not edit. -->

Canonical inventory of every public subpath and TypeScript export in `adonia-roles`.

## `adonia-roles`

| Export | Kind | Source | Summary |
| --- | --- | --- | --- |
| `assertPermissionSlug` | function | `packages/roles/src/permission_slug.ts:16` | Validate a permission declared by application code before it reaches SQL. |
| `assertRoleSlug` | function | `packages/roles/src/models.ts:11` | Validate a role slug before using it in a scoped lookup. |
| `assignRole` | function | `packages/roles/src/assignments.ts:137` | Assign one role. Returns `false` when the exact assignment already exists. |
| `clearPermissionCache` | function | `packages/roles/src/authorization.ts:120` | Drop every memoized permission set for one request context. |
| `createRolesResource` | function | `packages/roles/src/resource.ts:99` | Build the role-management resource registered by `rolesPlugin`. |
| `DefaultRoleDefinition` | type-only interface | `packages/roles/src/seeder.ts:6` | One code-first role installed by `seedDefaultRoles`. |
| `defineDefaultRoles` | function | `packages/roles/src/seeder.ts:23` | Validate default roles at module load while retaining the caller's literal type. This helper performs no I/O; pass its result to `seedDefaultRoles`. |
| `GLOBAL_TENANT` | constant | `packages/roles/src/authorization.ts:15` | Tenant key used by non-tenant panels. |
| `hasPermission` | function | `packages/roles/src/authorization.ts:143` | Bouncer-compatible permission lookup. Exact, resource wildcard, and global wildcard grants are resolved for one panel and tenant, then memoized per `ctx`. |
| `invalidatePermissionCache` | function | `packages/roles/src/authorization.ts:125` | Drop one user's panel- and tenant-scoped memo after a role mutation. |
| `isPermissionSlug` | function | `packages/roles/src/permission_slug.ts:9` | Whether `value` is `<resource>.<ability>`, `<resource>.*`, or `*`. |
| `panelKey` | function | `packages/roles/src/authorization.ts:18` | Normalize a panel identifier used to scope permission grants. |
| `Permission` | class | `packages/roles/src/models.ts:19` | Persisted permission grant. |
| `permissionLabel` | function | `packages/roles/src/permission_slug.ts:39` | Human label used by the roles resource when none was declared. |
| `permissionMatches` | function | `packages/roles/src/permission_slug.ts:31` | Resolve one persisted grant against a concrete permission. Wildcards only occupy the whole grant or the whole ability segment; partial globs never match. |
| `PermissionPolicy` | class | `packages/roles/src/policy.ts:14` | Bouncer-compatible base policy backed by `adonia-roles` grants. |
| `PermissionSlug` | type-only type | `packages/roles/src/permission_slug.ts:2` | A persisted permission grant or a concrete permission being checked. |
| `registerRolesResource` | function | `packages/roles/src/index.ts:31` | Register one configured role-management resource through the manifest ABI. |
| `resolveRole` | function | `packages/roles/src/assignments.ts:94` | Resolve a role and prove it belongs to the requested tenant. |
| `revokeRole` | function | `packages/roles/src/assignments.ts:167` | Revoke one role. Returns whether an assignment row was removed. |
| `Role` | class | `packages/roles/src/models.ts:35` | Panel- and tenant-scoped role managed by the Adonia resource. |
| `ROLE_SLUG_PATTERN` | constant | `packages/roles/src/models.ts:7` | Code-first role slugs are lower-case kebab identifiers. |
| `RoleAssignmentAudit` | type-only interface | `packages/roles/src/assignments.ts:18` | Optional actor and explicit panel bus for assignment activity events. |
| `RoleReference` | type-only type | `packages/roles/src/assignments.ts:15` | A role model, numeric id, or tenant-unique slug. |
| `ROLES_MIGRATION` | constant | `packages/roles/src/doctor.ts:7` | Published migration that creates every roles table. |
| `ROLES_MIGRATIONS` | constant | `packages/roles/src/index.ts:18` | Absolute directory containing the package's publishable Lucid migration. |
| `ROLES_VERSION` | constant | `packages/roles/src/version.ts:2` | Package version generated from package.json; do not edit directly. |
| `rolesManifest` | constant | `packages/roles/src/index.ts:21` | Unconfigured package manifest used by installers and migration discovery. |
| `RolesPermissionOption` | type-only type | `packages/roles/src/resource.ts:26` | One permission shown by the role editor's checkbox matrix. |
| `rolesPlugin` | function | `packages/roles/src/index.ts:42` | Build the installable manifest for a panel's role manager. |
| `RolesResourceAuthorization` | type-only type | `packages/roles/src/resource.ts:34` | Explicit gate for access to the privileged role-management resource. |
| `RolesResourceOptions` | type-only interface | `packages/roles/src/resource.ts:41` | Configuration for one panel's generated roles resource. |
| `rolesTablesDoctorCheck` | constant | `packages/roles/src/doctor.ts:12` | Verifies that Lucid has applied the roles package migration. |
| `RoleSyncResult` | type-only interface | `packages/roles/src/assignments.ts:195` | Observable delta returned by `syncRoles`. |
| `RoleUser` | type-only interface | `packages/roles/src/authorization.ts:7` | Minimal identity accepted by assignment and authorization helpers. |
| `roleUserId` | function | `packages/roles/src/authorization.ts:39` | Normalize the host user primary key stored by `adonia_user_roles`. |
| `seedDefaultRoles` | function | `packages/roles/src/seeder.ts:45` | Idempotently upsert permissions and default roles, then synchronize each role's permission pivot in one transaction. |
| `SeedDefaultRolesOptions` | type-only interface | `packages/roles/src/seeder.ts:13` | Scope and definitions accepted by the idempotent role seeder. |
| `syncRoles` | function | `packages/roles/src/assignments.ts:205` | Replace one user's roles inside one tenant. Duplicate references collapse to one assignment, and an already-synchronized set performs no writes. |
| `TenantIdentifier` | type-only type | `packages/roles/src/authorization.ts:12` | Tenant identifiers are normalized to strings in the pivots. |
| `tenantKey` | function | `packages/roles/src/authorization.ts:26` | Normalize a tenant id, securely rejecting empty or non-finite identities. |

Source: https://adonia.pages.dev/reference/api/roles/index.mdx