Roles and permissions

ICAP authorizes actions with tenant-scoped roles. A role is a named collection of permission identifiers. A role assignment gives that role to an external HID-authenticated user ID for one tenant.

HID Authentication Service token
  → authenticated user identifier
  → role assignments in the request tenant
  → permissions from assigned roles
  → endpoint authorization

ICAP does not create, store, or disable user accounts. Manage authentication identities through HID Authentication Service, and use ICAP only to grant or remove their access to ICAP operations.

Manage access

1. Get the available permission catalog from GET /permission.

2. Create a role with a concise business purpose and only the required permissions.

3. Create a role assignment under that role with the target userId.

4. Verify assignments by listing the role's assignments or a user's roles.

Prefer task-focused roles, such as a visitor receptionist role or an access-data administrator role, instead of assigning broad permissions to every integration user.

Create a role for an integration

Use an already-authorized tenant administrator for this one-time sequence. Do not give an integration principal the administrator role simply because it needs its first permissions.

1. Read GET /permission and select only permissions present in that tenant's catalog.

2. Create the role with POST /role. The request requires name and a permissions array.

3. Assign it to the HID-authenticated principal with POST /role/{roleId}/assignment, supplying its external userId.

4. Obtain a token for that principal and test one read and one intended write in a non-production tenant. Use GET /user/{userId}/role, when authorized, or list the role assignments to verify the assignment.

For example, an administrator can create a role for the quickstart with the permission list:

{
  "name": "Non-production quickstart integration",
  "permissions": [
    "AccessUnitCreate",
    "CardCredentialCreate",
    "CardTypeCreate",
    "IdentityAccessUnitAssign",
    "IdentityAccessUnitList",
    "IdentityCreate",
    "IdentityCredentialAssign",
    "IdentityCredentialList",
    "IdentityGet",
    "IdentityList"
  ]
}

Built-in roles and constraints

Tenant registration creates the tenant administrator role and assigns it to the provided administrator. The tenant administrator has the tenant's administrator permission catalog; it cannot be edited or deleted, and its final assignment cannot be removed.

Custom roles may contain only permissions available to the tenant administrator catalog. Direct per-user permission grants are not supported—use role assignments. A user can hold roles in more than one tenant, but each tenant's permissions are evaluated independently.

Safe changes

Roles are versioned: read the current role, then send its raw numeric version in If-Match for PATCH or delete. Role assignments are not versioned. Removing a role assignment immediately affects the user's effective access in that tenant.

Start troubleshooting authorization failures with authentication, then check the caller's tenant path, role assignments, and role permission list. Endpoint permissions and schema details are in the API reference and direct API Swagger (ICAP).