Authentication

Regular login flow

1. Create a user login challenge

Use POST /auth/login/init to create a login challenge.

• The endpoint returns a challenge that the user must sign.
• If the user has a credential of kind PasswordProtectedKey, a temporary one time code must be passed in the loginCode field.
  • Obtain this code first by calling POST /auth/login/code.
  • This step is required because the login challenge endpoint is unauthenticated and returns the user’s encrypted private key.
  • The one time code verifies the user’s identity before the encrypted private key is returned.

• If the user has at least one discoverable WebAuthn credential, the username field is optional. This enables a usernameless login flow.

2. Get the user to sign the challenge

The method used to sign the login challenge depends on the user’s credential type:

• Passkey (WebAuthn): The browser or operating system signs the challenge using WebAuthn APIs and the user’s device.
• Personal access token: The private key associated with the PAT signs the challenge.
• Service account token: The private key associated with the service account signs the challenge.

3. Complete the user login

Use POST /auth/login to complete the login. This final step validates the signed challenge and returns an authentication token for the user.The credential type used during login is determined by the kind field inside the firstFactor and secondFactor objects. Supported credential kinds include:

• Fido2: The challenge is signed using WebAuthn on the user’s device.
• Key: The challenge is signed using the user’s private key.
• PasswordProtectedKey: The challenge is signed using the decrypted private key that was returned during the login challenge step.

SSO login flow

Obtain the SSO URL

Use POST /auth/login/sso/init to initiate the SSO login.

• The endpoint returns a URL for the user’s identity provider.
• Redirect the user to this URL so they can authenticate.

Note: After authentication, the identity provider redirects the user to the redirect URL configured in your SSO provider's dashboard.

• Ensure that this redirect URL is also whitelisted in your IBM Digital Asset Haven settings.
• See the SSO setup tutorial for details.

The redirect URL includes a code and state, which are required for the next step.

2. Log the user in

Use POST /auth/login/sso with the code and state returned during the redirect.The endpoint logs the user in and returns an authentication token.

Social login flow

Use POST /auth/login/social to obtain an authentication token for users logging in through supported social identity providers.

Delegated users login flow