External Permissions
External Permissions are permissions that don't control access to anything within Trivore ID itself — instead, they give access to external functions defined by whichever apps and services read them. Trivore ID stores the permission metadata and the record of who holds which external permission, and lets you grant and revoke those permissions through APIs and the Management UI.
Defining External Permissions
External Permissions are organised into External Permission Groups. Every permission under one group is managed by the same people and visible to the same clients and apps — most applications only need one or a few permission groups; create a new group only when a set of permissions needs different management or visibility rules.
Creating new External Permission Groups requires the built-in Manage External Permissions permission.
When creating a group, you configure:
- an Owner (defaults to the creating account),
- who can view and manage permission definitions in the group (read or read+write access),
- who can grant and revoke the permissions in the group, and
- who the group is visible to — Management API Clients and OAuth2 Apps are configured separately.
Then create External Permissions within the group. Each permission has a name, description, and an optional external ID — a code your application can use, provided via the external permission query APIs — plus any custom fields you want to attach.
Permission management with the management console
Open External Permissions from the Main Menu. The table view shows the permission groups you have at least read access to, expandable to show the permissions within each. Add group / Edit group / Delete group manage groups (including exporting and importing a group as JSON); Add permission / Edit permission / Delete permission manage permissions within the selected group.
Permission management with the Management API
Group and permission definitions are managed via /api/rest/v1/externalpermission/group:
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /externalpermission/group | Search External Permission Groups |
| POST | /externalpermission/group | Create a new External Permission Group |
| GET / PUT / DELETE | /externalpermission/group/{groupId} | Get, update, or delete a group |
| GET | /externalpermission/group/{groupId}/permission | Search External Permissions within a group (supports filtering by id, externalId, name, description, and custom fields) |
| POST | /externalpermission/group/{groupId}/permission | Create an External Permission |
| GET / PUT / DELETE | /externalpermission/group/{groupId}/permission/{id} | Get, update, or delete a permission |
Read and write access to a group's endpoints is governed by the group's own configuration (its
owner and the "who can view/manage" and "who can grant/revoke" lists). The admin-level
permissions EXTERNAL_PERMISSION_READ_ALL and EXTERNAL_PERMISSION_WRITE_ALL grant read or
write access to all groups, bypassing per-group configuration. See your instance's /apidoc
(External Permissions section) for the full request/response reference.
Granting and revoking external permissions
Granting or revoking a permission requires read+write ("manage") access to its group — either
through the group's own "who can grant and revoke" configuration, or via
EXTERNAL_PERMISSION_WRITE_ALL. You'll also need whatever access is needed to modify the
target the permission is being granted to (for example, a role or a user account).
An external permission can be held two ways: directly by a target (such as a user account), or indirectly, by being granted to a Custom Role that the target holds through Group membership — consistent with how Roles generally reach users.
With the management console
Open the Accounts view, select a user, then Actions → External permissions. A dialogue opens showing the permissions granted directly to the account and those granted indirectly through groups and roles, together with a Grant more permissions option.
With the Management API
Granting or revoking a permission on a Custom Role has dedicated endpoints:
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/rest/v1/role/custom/{roleId}/externalpermissions | Read external permissions granted to the role |
| POST | /api/rest/v1/role/custom/{roleId}/externalpermissions/grant/{permissionId} | Grant a permission to the role |
| POST | /api/rest/v1/role/custom/{roleId}/externalpermissions/revoke/{permissionId} | Revoke a permission from the role |
Granting a permission directly to a target (rather than through a role) doesn't have a
dedicated external-permission endpoint — it's done through the general-purpose
Authorisations API (/api/rest/v1/authorisation), the same mechanism
used for other subject/object access relationships in Trivore ID.
Querying user's external permissions
When querying as a user, the calling user sees only permissions from groups where they have read-level management access.
When querying with Management API Client credentials, the client sees permissions only from groups where it's on the "visible to" list. The same applies to an OAuth2 app querying with its own credentials.
With the management console
Open the Accounts view, select a user, then Actions → External permissions — see above for what the dialogue shows.
With the Management API
The permission-search endpoints above filter by permission attributes, not by holder — querying what a specific target holds (direct or indirect grants) goes through the Authorisations API rather than a dedicated external-permission endpoint.
With OpenID Connect claims and the UserInfo endpoint
Not currently supported directly: Custom OIDC Scopes only support Audience, Hardcoded claim, and User Custom Field mappers today — there's no mapper type for External Permissions. If you need external permission data available in a token or the UserInfo response, you'd need to mirror it into a user custom field and expose that instead.