Authorisation

Role-based permissions for the Compliance Dashboard and GraphQL API are available only to Enterprise customers. On a new instance, the 21travel Keycloak realm contains the permission roles, but new users receive none of them automatically. Assign roles before users sign in. A user without the required roles can authenticate but cannot perform the protected actions.

Give a User Full Access

If you do not need to restrict a user's access, assign travel.admin. This composite role grants all the read and write permissions listed below. Do this for each new user who should have full access; the Keycloak admin account used to manage users is separate from a Compliance Dashboard user.

Assign Roles to a User

Sign in to the Keycloak Administration Console and select the 21travel realm.
Open Users, select the user, and open Role mapping.
Click Assign role and choose Client roles.
Find travel.admin under the account client, or select the specific roles the user needs, and click Assign.
Ask the user to sign out and sign in again so their access token includes the new roles.

User with the travel.admin client role

The roles belong to the account client, not the realm. The reference deployment uses account as its compliance client. If you configure a different compliance client, create the corresponding roles there and ensure they are included in the user's access token.

Choose a Role Set

Client role	Access granted
`travel.read`	All read permissions in the table below.
`travel.write`	All write permissions in the table below.
`travel.admin`	Both `travel.read` and `travel.write`.

travel.write does not include travel.read. Assign both for users who need to view and change all data, or use travel.admin. You can assign individual roles for narrower access.

Client role	Access granted
`travel.configuration.read`	View your VASP configuration and ownership portal settings.
`travel.configuration.write`	Change your VASP configuration and ownership portal settings.
`travel.transactions.read`	View and export transactions, generate transaction reports, and receive transaction updates.
`travel.transactions.write`	Register, send, approve, decline, confirm, or cancel transactions.
`trpd.customers.read`	View and search customers in the Travel Address Book.
`autod.customers.write`	Register customers and update their wallet addresses.
`trpd.vasps.read`	View TRP counterparty VASPs.
`trpd.vasps.write`	Manage TRP counterparty VASPs.
`trustd.vasps.read`	View TRUST counterparty VASPs.
`trustd.vasps.write`	Manage TRUST counterparty VASPs.
`email.vasps.read`	View email counterparty VASPs.
`email.vasps.write`	Manage email counterparty VASPs.
`aopd.proofs.read`	View and export self-hosted wallet proofs and receive proof updates.
`aopd.proofs.write`	Request, register, review, and update self-hosted wallet proofs.
`aopd.risk_scores.write`	Set or refresh risk scores for self-hosted wallet proofs.
`trpd.risk_scores.write`	Set or refresh transaction risk scores.
`autod.audit_logs.read`	View and export the audit log.

Create Your Own Role Bundles

You can create a Keycloak composite client role to give a team a chosen subset of the individual roles above. Assign the bundle to users instead of assigning each permission separately. For example:

Bundle example	Associated client roles	Result
`travel.audit_reviewer`	`travel.transactions.read`, `autod.audit_logs.read`	Can inspect transactions and audit logs, but cannot change transactions or open the Travel Address Book and proofs.
`travel.trp_vasp_manager`	`trpd.vasps.read`, `trpd.vasps.write`	Can view and manage TRP counterparty VASPs without access to TRUST or email VASPs.

To create either bundle in the 21travel realm:

Open Clients → account → Roles and click Create role. Give it the example name, or a name that describes your team's duties, and save it.
Open the new role and choose Action → Add associated roles. Select Client roles from the account client and add the individual roles in the table. This makes the new role a composite.
Assign the new role to users through Users → the user → Role mapping → Assign role → Client roles. Users inherit its associated permissions.

For more on Keycloak composite roles, see the Keycloak Server Administration Guide.

User Interface Behaviour

The dashboard hides configuration navigation when the user has neither configuration role, and hides the audit log entry without autod.audit_logs.read. Controls for actions without a required write role are disabled and show the missing permission when hovered over. GraphQL checks roles independently of the dashboard: a request for a protected field without its role returns an error such as Forbidden: missing required role 'travel.transactions.read'. GraphQL subscriptions require the matching read role as well.

API Integrations

For API integrations, assign roles to the user or service account that obtains the access token. The token must contain the roles for the configured compliance client. For a client credentials integration, open that API client in Keycloak and assign its service account the required account client roles under Service account roles.

Keyboard shortcuts