POST /session/start

Content

• Overview
• API URL
• Input Parameters
• Response Parameters
• Error Codes
• Revision History

Overview

The Session Start API opens a user session. This API is a bit of a unique case with regards to all Process-specific APIs. Whereas the POST /process/start/{processName}invokes most Processes, and optionally accepts no payload, Session Start starts the Authenticate User Process and accepts a mandatory payload.

API URL

• POST /session/start

Input Parameters

As you might expect, this API requires two key items: an authnIdentifier and credential.

authnIdentifier

Authentication identifiers (or authN IDs) are commonly known as "usernames." Every ULM User ID requires at least one verifiable authN ID, either an email address or mobile number.

Note: ULM Cloud also supports a non-verifiable authN ID known as an alias that a user can add to their User ID with the Add/Update Email, Mobile, or Alias Process. Users can then use their alias for authentication purposes instead of their email or mobile. However, the User must still have at least one verifiable email or mobile authN ID.

credential

Credential is commonly known as "password."

Note on Password Rules: Whereas all ULM User IDs require at least one verifiable authN ID, ULM Cloud supports passwordless user creation and authentication options with the Onboard and Authenticate User with Social Account Process. However, an existing user without a password cannot dissociate their user ID.

Response Parameters

If successful, ULM Cloud will open a user session, and return the following data:

{
    "processId": "eec918ff-5db4-4fee-a601-5ff76a099c8e",
    "lastStep": true,
    "runtimeId": 229,
    "userId": 1,
    "userAuthenticated": true
}

Parameter	Description
processId	Unique identifier for the current instance of this Process. The client application UI must provide this ID in every subsequent PUT /process/steprequest in order to continue and complete the Process.
lastStep	Boolean that indicates whether or not this was the last step in the Process.
runtimeId	Identifier of the a runtime currently associated to the User ID.
userAuthenticated	Boolean that confirms that the Process / API has authenticated the user.
userId	The unique identifier of the ULM User entity. Depending on the nature of the client application, you may want to leverage the userId in a GET user/{userId} API so as to retrieve and load up any pertinent ULM User details.

Error Codes

See Common Process Error Codes for more information. Individual Process topics also contain examples of error scenarios.

Process Specific Error Codes

HTTP Status	Type	ULM Error Code	Description
401	operation error	user-profile-locked	The user's profiles is locked.
401	operation error	authentication-required	One or more of the following is true: - Authentication identifier is not valid. - Credential (password) is not valid. - User not found. - reCAPTCHA verification code is not valid.
401	operation error	user-activating	The authentication identifier provided is in activating status, and the process is not configured to allow authentication via activating authentication identifiers.
401	operation error	invalid-code	The process prompted for a 2FA code, but the code provided was invalid.

Revision History

Version	Description
2020.09	Added this topic.