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

Each action you can take in the API corresponds to a single permission, for example:

• "CREDENTIAL_LIST" enables the GET method on /api/credential/v1
• "KEY_CREATE" enables the POST method on /api/key/v1
• "PROOF_CLAIMS_DELETE" enables the DELETE method on /api/proof-request/v1/:proofRequestId/claims

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. Access to this endoints is controlled in the configuration.

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

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.

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.