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.

Trial users

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

tip

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.

info

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 entities
• VERIFIER grants an organization permissions to create credential and proof schemas, request proofs from wallet holders, access verification- related endpoints, and OpenID provider operations
• HOLDER 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.

info

• 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:

1. Desk has been integrated with OpenID Bridge

2. 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.