Authentication and authorization

Authorization manager operations

Desk API

Except for the login endpoint, all requests to the Desk API must be authenticated.

Logging in

Logging in to the Desk requires choosing a login method and passing the associated parameters. The following methods are supported.

Methods

Method	Description
PASSWORD	Use email and password for login.
ACCESS_CODE	Use an OpenID Connect authorization_code for login. For Bridge-enabled Desk instances, this is used for logging in with a credential in the user's digital wallet.

Access code

Users can log in using OpenID Connect with the authorization code flow.

This can come from a OpenID Bridge integration or from a custom OIDC integration. Use the authorization code returned from the OIDC integration during the login:

{
  "method": "ACCESS_CODE",
  "accessCode": "{authorization_code}"
}

Login with credential

The Desk API can be configured to enable users to log in using a credential. This creates a password-free login experience for Desk users.

The following conditions must be true before the user can use a credential to log in to the Desk:

• The Desk instance includes an OpenID Bridge license. See the product page.
• Bridge has been integrated. See the integration guide.
• The Desk API is configured to enable credential login. This is described here.
• The user has enabled credential login via the profile endpoint and has accepted the issued credential into their digital wallet. See the profile resource page.

To configure the system to enable users to log in with a credential, add an entry for login to the application.yaml and provide basic parameters for issuing the login credential:

login:
  url: ${YOUR-FRONTEND-URL}/login // Your login url
  credential:
    enabled: true // If true, enables users to use the login with credential feature
    issuerDid: {UUID} // Specify the DID from which the login credential will be issued
    exchange: OPENID4VC
    credentialSchemaId: {UUID} // Specify the schema of the credential that will be issued
    emailPath: email // Key of email claim

The login.credential entry determines which credential will be issued to Desk users and how. Since email is the only claim used for logging in to the Desk with a credential, it is recommended to create a new credential schema with email as the only claim.

Stay logged in

During login, the stayLoggedIn boolean is an optional parameter.

If nothing or false is passed, the session token expires after 12 hours. Call the /api/auth/v1/refresh endpoint before the session expires and the current token is refreshed, keeping the session valid and updating times for expiration values. If the session expires without a refresh, the token is no longer usable.

If true is passed, the session token expires after 30 days.

After logging in

Successful calls to the login endpoint return a session token and information about when the session expires or needs refreshment along with organization and permission information:

{
  "token": "{{sessionToken}}",
  "expiresIn": "2024-03-28T22:14:31.462Z",
  "refreshExpiresIn": "2024-04-27T10:14:31.466Z"
}

The token should be stored and used by having the following header in all further requests:

Authorization: Bearer <JWTToken>