Skip to main content

Roles

The roles of the management API and the endpoints that accept them, generated from the backend's role enum and the @Secured decorators of its controllers. How to assign roles to clients and users is described in Tenants and access.

A caller passes the role check if it has any of an endpoint's roles; where the roles are joined with "and", it needs all of them. With the built-in OAuth2 server these are the client's current roles (revoke access), with Keycloak the roles in the token. Most endpoints also act on the tenant in the token and refuse a token without one, such as the root client's, with 403 "This endpoint requires a tenant context". A token whose tenant does not exist counts as one without. Without a tenant, tenants:manage works for the /api/tenant endpoints, for rotating client secrets and for the cache endpoints under /api/cache (not DELETE /api/cache/trust-list/sequence-numbers), and tenants:manage or tenant:admin for POST /api/config-bundles/documents/upgrade. With tenants:manage, the cache endpoints cover the caches of all tenants; with issuance:manage or presentation:manage they need a tenant and cover only that tenant (which entries). GET /api/config-bundles/resources/:kind and GET /api/config-bundles/resources/:kind/:id/document also check the kind (which roles).

Granting roles​

A caller that creates or changes a client (/api/client) or a person (/api/user) can grant only these roles:

The caller hasIt can grant
tenants:manageevery role
tenant:adminevery role except tenants:manage and tenant:admin
neitherthe roles it holds, except tenants:manage and tenant:admin

A caller can change or delete a client or person, or rotate a client's secret, only if it holds or can grant each of its roles; tenants:manage can rotate the secret of any client, except a file-managed one, which answers 409 until a token of the client's tenant detaches it. A change may keep roles the caller cannot grant, such as tenant:admin for a tenant:admin caller, but not add them. With Keycloak, creating a client that takes over an existing Keycloak client of the tenant needs both: the caller must be able to manage that client, and grant each requested role, since none counts as one the client already has (Keycloak SSO). The same rules apply to the clients that an imported configuration bundle creates, changes or deletes, and its plan already reports a refusal. Other requests answer 403.

With Keycloak, the roles assigned in Keycloak count as well, including those from groups and composite roles. Roles of the realm-management client, also from groups and composite roles, and any other client role mapped directly to the account, count as roles the caller does not hold, so such accounts are managed in Keycloak only.

Roles​

The endpoint count of a role includes only the endpoints the role opens on its own, not those that need it together with another role.

RoleDescriptionEndpoints
presentation:manageTo manage verifier resources: presentation configurations, OpenID Connect clients, trust lists, federation trust anchors, key chains, webhook endpoints and session settings, and, together with registrar:manage, to request a verifier registration certificate from the EUDI Hub57
presentation:requestTo create presentation requests, read presentation configurations and read, cancel or delete presentation sessions13
issuance:manageTo manage issuer resources: credential and issuance configurations, attribute providers, status lists and their settings, trust lists, federation trust anchors, key chains, webhook endpoints and session settings, to revoke, suspend or reinstate issued credentials, and, together with registrar:manage, to request an issuer registration certificate from the EUDI Hub63
issuance:offerTo create credential offers, complete or fail deferred issuance, read, cancel or delete issuance sessions and read the status of their credentials12
clients:manageTo manage the tenant's API clients with the roles the caller may grant, and read its audit log11
users:manageTo manage the tenant's human users with the roles the caller may grant5
tenants:managePlatform operator role, needs no tenant: to create, change and delete any tenant, rotate client secrets, see the cached status lists and clear the trust list, federation and status list caches of all tenants; with a token of a tenant also to use its configuration bundles, key export and KMS provider settings29
tenant:adminTo manage the current tenant's full configuration: configuration bundles, key export and KMS provider settings; a caller with it may grant every role except tenants:manage and tenant:admin19
registrar:manageTo request certificates from a registrar such as the EUDI Hub: list the organizations of a portal token and request access certificates for access key chains; registration certificates also need presentation:manage or issuance:manage3
audit:readTo read the tenant's audit log3
sessions:readTo read the tenant's issuance and presentation sessions, their logs, events and statistics and the status of issued credentials, without creating, cancelling or deleting them6
credentials:statusTo revoke, suspend or reinstate the credentials issued in a session and read their status2
keys:manageTo create, import, rotate, change and delete key chains and read them and the KMS providers; key export and KMS provider settings need tenant:admin or tenants:manage14

Endpoints​

MethodPathRequired roles
GET/api/admin/audit-logsclients:manage or audit:read
GET/api/admin/audit-logs/retentionclients:manage or audit:read
GET/api/admin/audit-logs/searchclients:manage or audit:read
GET/api/auth/meany valid access token
DELETE/api/cacheissuance:manage or presentation:manage or tenants:manage
GET/api/cache/statsissuance:manage or presentation:manage or tenants:manage
DELETE/api/cache/status-listissuance:manage or presentation:manage or tenants:manage
DELETE/api/cache/trust-listissuance:manage or presentation:manage or tenants:manage
DELETE/api/cache/trust-list/sequence-numbersissuance:manage or presentation:manage
GET, POST/api/clientclients:manage
DELETE, GET, PATCH/api/client/:idclients:manage
POST/api/client/:id/rotate-secretclients:manage or tenants:manage
POST/api/config-bundles/documents/upgradetenants:manage or tenant:admin
GET/api/config-bundles/exporttenants:manage or tenant:admin
POST/api/config-bundles/importtenants:manage or tenant:admin
POST/api/config-bundles/import/archivetenants:manage or tenant:admin
GET/api/config-bundles/operationstenants:manage or tenant:admin
GET/api/config-bundles/operations/:idtenants:manage or tenant:admin
POST/api/config-bundles/operations/:id/acknowledge-interruptiontenants:manage or tenant:admin
POST/api/config-bundles/plantenants:manage or tenant:admin
POST/api/config-bundles/plan/archivetenants:manage or tenant:admin
GET/api/config-bundles/resourcestenants:manage or tenant:admin
GET/api/config-bundles/resources/:kindtenants:manage or tenant:admin or issuance:manage or presentation:manage or clients:manage or keys:manage
POST/api/config-bundles/resources/:kind/:id/detachtenants:manage or tenant:admin
GET/api/config-bundles/resources/:kind/:id/documenttenants:manage or tenant:admin or issuance:manage or presentation:manage or clients:manage or keys:manage
POST/api/config-bundles/resources/:kind/:id/reattachtenants:manage or tenant:admin
POST/api/config-bundles/resources/:kind/:id/reattach/plantenants:manage or tenant:admin
POST/api/eudi-hub/access-certificateregistrar:manage
POST/api/eudi-hub/organization-detailsregistrar:manage
POST/api/eudi-hub/organizationsregistrar:manage
POST/api/eudi-hub/registration-certificate/issuerregistrar:manage and issuance:manage
POST/api/eudi-hub/registration-certificate/presentationregistrar:manage and presentation:manage
GET, POST/api/federation-trust-anchorissuance:manage or presentation:manage
DELETE, GET, PATCH/api/federation-trust-anchor/:idissuance:manage or presentation:manage
GET/api/frontend-configany valid access token
GET, POST/api/issuer/attribute-providersissuance:manage
DELETE, GET, PATCH/api/issuer/attribute-providers/:idissuance:manage
GET, POST/api/issuer/configissuance:manage
GET, POST/api/issuer/credentialsissuance:manage
DELETE, GET, PATCH/api/issuer/credentials/:idissuance:manage
POST/api/issuer/deferred/:transactionId/completeissuance:offer
POST/api/issuer/deferred/:transactionId/failissuance:offer
POST/api/issuer/offerissuance:offer
GET, POST/api/issuer/webhook-endpointsissuance:manage or presentation:manage
DELETE, GET, PATCH/api/issuer/webhook-endpoints/:idissuance:manage or presentation:manage
GET, POST/api/key-chainissuance:manage or presentation:manage or keys:manage
DELETE, GET, PUT/api/key-chain/:idissuance:manage or presentation:manage or keys:manage
GET/api/key-chain/:id/csrissuance:manage or presentation:manage or keys:manage
GET/api/key-chain/:id/exporttenants:manage or tenant:admin
POST/api/key-chain/:id/rotateissuance:manage or presentation:manage or keys:manage
GET, PUT/api/key-chain/access/defaultissuance:manage or presentation:manage or keys:manage
POST/api/key-chain/importissuance:manage or presentation:manage or keys:manage
GET/api/key-chain/providersissuance:manage or presentation:manage or keys:manage
DELETE, GET, PUT/api/key-chain/providers/configtenants:manage or tenant:admin
GET/api/key-chain/providers/healthissuance:manage or presentation:manage or keys:manage
GET/api/sessionissuance:offer or presentation:request or sessions:read
DELETE, GET, PUT/api/session-configissuance:manage or presentation:manage
DELETE/api/session/:idissuance:offer or presentation:request
GET/api/session/:idissuance:offer or presentation:request or sessions:read
POST/api/session/:id/cancelissuance:offer or presentation:request
GET/api/session/:id/credential-statusissuance:offer or issuance:manage or credentials:status or sessions:read
GET/api/session/:id/eventsissuance:offer or presentation:request or sessions:read
GET/api/session/:id/logsissuance:offer or presentation:request or sessions:read
POST/api/session/revokecredentials:status or issuance:manage
GET/api/session/statsissuance:offer or presentation:request or sessions:read
DELETE, GET, PUT/api/status-list-configissuance:manage
GET, POST/api/status-listsissuance:manage
DELETE, GET, PATCH/api/status-lists/:listIdissuance:manage
POST/api/storageissuance:manage
GET, POST/api/tenanttenants:manage
DELETE, GET, PATCH/api/tenant/:idtenants:manage
GET, POST/api/trust-listissuance:manage or presentation:manage
DELETE, GET, PUT/api/trust-list/:idissuance:manage or presentation:manage
GET/api/trust-list/:id/exportissuance:manage or presentation:manage
GET/api/trust-list/:id/versionsissuance:manage or presentation:manage
GET/api/trust-list/:id/versions/:versionIdissuance:manage or presentation:manage
GET, POST/api/userusers:manage
DELETE, GET, PATCH/api/user/:idusers:manage
GET/api/verifier/configpresentation:manage or presentation:request
POST/api/verifier/configpresentation:manage
DELETE, PATCH/api/verifier/config/:idpresentation:manage
GET/api/verifier/config/:idpresentation:manage or presentation:request
POST/api/verifier/config/issuer-metadata/resolvepresentation:manage or presentation:request
POST/api/verifier/config/schema-metadata/resolvepresentation:manage or presentation:request
POST/api/verifier/config/schema-metadata/resolve-jwtpresentation:manage or presentation:request
POST/api/verifier/offerpresentation:request or presentation:manage
GET, POST/api/verifier/oidc-clientspresentation:manage
DELETE, GET, PATCH/api/verifier/oidc-clients/:idpresentation:manage
POST/api/verifier/oidc-clients/:id/secretspresentation:manage
DELETE, PATCH/api/verifier/oidc-clients/:id/secrets/:secretIdpresentation:manage
GET/api/versionany valid access token
POST/issuers/:tenantId/authorize/interactive/complete-web-auth/:authSessionissuance:offer