Authentication and authorization
The Desk API uses a multi-layered authentication approach that relies on the OAuth 2.0/OpenID Connect (OIDC) Authorization Code Flow. Valid authentication to your IAM solution produces an access token. This token is given to the Desk's Security Token Service (STS) to exchange it for an application-specific token. This application token gives you access to permissioned actions.
API clients can no longer login directly to the Desk API with username and password. If you are a trial user and you wish to have API access, please reach out to us.
STS
Your IAM is configured to produce tokens containing roles, with each role corresponding to a set of organization-permissions pairings. The STS validates this access token and exchanges it for an application-specific authorization token to be used for subsequent requests to backend components.
Token exchange
The STS validates access tokens to ensure:
- The token is valid and not expired
- The token issuer and audience values match what is in the system configuration
- The token is signed by a public key of the JWKS in the system configuration
Roles and permissions
The Desk uses a multi-layered authorization system where access to any given action depends on the intersection of several role types working together. At its foundation, most API actions require specific permissions. To enable fine-grained control in complex, multi-tenant environments, these permissions are granted through multiple overlapping layers of roles.
A user's effective permissions are determined by where all these layers intersect:
- Permissions form the base layer, with most API endpoints requiring one or more permissions to access
- Custom roles bundle permissions together into logical groups that defined by an admin user
- Organization roles provide pre-configured permission sets tied to your organization's function (issuer, verifier, holder)
- IAM roles map your custom roles to specific organizations, controlling which roles apply where
When you make an API call, the system checks your active organization and evaluates all applicable roles to determine your final permission set. You can only perform actions where you have the required permissions through this intersection of role layers.
Permissions
For the complete list of available permissions, see the response schema of the get-organisations endpoint.
Each action you can take in the API corresponds to a single permission, for example:
Example permission | What the permission enables |
---|---|
CREDENTIAL_LIST | GET method on /api/credential/v1 |
KEY_CREATE | POST method on /api/key/v1 |
PROOF_CLAIMS_DELETE | DELETE method on /api/proof-request/v1/:proofRequestId/claims |
Custom roles
Each role contains a list of permissions. In the following example we have a role whose permissions enable a limited set of credential issuing actions:
{
"id": "e09d9dff-631b-4ef6-9533-1b24a5414bf6",
"name": "EXAMPLE_ROLE",
"permissions": [
"CREDENTIAL_LIST",
"CREDENTIAL_DETAIL",
"CREDENTIAL_ISSUE",
"CREDENTIAL_SHARE",
"CREDENTIAL_REACTIVATE",
"CREDENTIAL_SCHEMA_LIST",
"CREDENTIAL_SCHEMA_DETAIL",
"DID_DETAIL",
"DID_LIST",
"DID_RESOLVE",
"HISTORY_DETAIL",
"HISTORY_LIST",
"KEY_LIST",
"KEY_DETAIL"
],
"createdDate": "2025-04-28T09:54:16.188Z",
"lastModified": "2025-04-28T09:54:16.188Z"
}
A user with this role can see and use identifiers and schemas and can issue credentials. They cannot suspend, revoke, or delete credentials, nor can they create identifiers and schemas.
Use /api/sts/role/v1
to create and manage roles. Only admin users can
access this endpoint.
Exceptions
- Some endpoints do not require authentication, for example:
- System configuration and build information
- Well-known URIs for service and configuration discovery
- Some protocol-specific Core endpoints used for issuance and presentation
- Some endpoints require authentication but have no corresponding
permission, for example:
- Profile endpoint for retrieving and updating user attributes
Organization roles
All organizations in the system are assigned some subset of functional roles:
ISSUER
grants an organization permissions to create credential schemas, issue and manage credentials, and retrieve these entitiesVERIFIER
grants an organization permissions to create credential and proof schemas, request proofs from wallet holders, access verification- related endpoints, and OpenID provider operationsHOLDER
grants an organization permissions to accept credentials, generate and share proofs with verifiers, and retrieve stored credentials and proofs
Admin users assign these roles when they create an organization, according
to the function the organization is expected to fulfill. An organization
might have multiple roles — for example, a university office could be both
an ISSUER
for diplomas and a VERIFIER
for employment verification.
These organizational roles establish the outer boundaries of what any user can do within an organization. Even if a user's custom roles include additonal permissions, they can only exercise permissions that are granted by their organization's functional roles. This ensures that organizations can only perform actions aligned with their designated purpose.
IAM roles
Where a role is a list of permissions granted for any given organization, an IAM role maps sets of roles to particular organizations:
{
"name": "string",
"organisationRoles": {
"orgId1": ["roleId1", "roleId2"],
"orgId2": ["roleId2"]
}
}
Each user is assigned a set of IAM roles in the IAM solution. On login, the IAM produces an access token containing the authorized IAM roles. The STS then exchanges the access token for the authorization token for accessing the relevant actions.
-
Use
api/sts/organisation/v1
to create and manage organizations. -
Use
/api/sts/iam-role/v1
to create and manage IAM roles.
Access to these endpoints are controlled in the configuration.
Resulting token
The payload of the token granted on login includes the user's permissions mapped to the organizations where they can exercise those permissions, looking something like this:
{
"sub": "{{USER-UUID}}",
"permissions": {
"KEY_DETAIL": ["{{ORG-1-UUID}}", "{{ORG-2-UUID}}"],
"CREDENTIAL_SCHEMA_SHARE": [
"{{ORG-1-UUID}}",
"{{ORG-3-UUID}}",
"{{ORG-4-UUID}}"
],
"DID_LIST": ["{{ORG-2-UUID}}"],
"HISTORY_LIST": [
"{{ORG-1-UUID}}",
"{{ORG-2-UUID}}",
"{{ORG-4-UUID}}",
"{{ORG-5-UUID}}"
]
}
}
Sessions and user attributes
The Desk stores basic information about users in the session.
Active organization
Users of the Desk have one organization active at any given time. Use
the /api/organisation/v1
to list all available organizations. To change
the active organizations, use api/organisation/v1/switch
.
User profile
The STS database stores basic user attributes. Retrieve this data from
the /api/profile/v1
endpoint. Application-specific attributes such as
your homepage on login and default language can be updated via the same
endpoint.
Log in with credential
If the following conditions are true, users can enable the ability to log in to Desk using a credential:
Desk has been integrated with OpenID Bridge
The feature is enabled in the configuration
When credentialLoginEnabled
is set to true
, the system creates and
issues a login credential. If a login credential already existed it is
revoked before the new credential is issued.
When set to false
, any issued login credential is revoked and removed
from the session.