POST /session/start - MarketONE — SaaS Knowledge Center

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 Process Start API invokes most Processes, and optionally accepts no payload, Session Start starts the Authenticate User Process and accepts a required payload.

API URL

POST https://{your.tenant.url}/session/start

Request 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 Storefront Gateway User ID requires at least one verifiable authN ID, either an email address or mobile number.Storefront Gateway 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: Whereas Storefront Gateway Users require at least one verifiable authN ID, Storefront Gateway also supports passwordless User creation and authentication options with the Onboard & Authenticate User with Social Process. However, an existing User without a password cannot be dissociated from that social account, unless they first add a password.

Response Parameters

If successful, Storefront Gateway will open a user session, and return the following data:

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

`processId`	Unique identifier for the current instance of this Process. The client application UI must provide this ID in every subsequent Process Step request (if any) 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 Storefront Gateway User entity.Depending on the nature of the client application, you may want to leverage the `userId`in a variety of user Storefront Gateway’s user management APIs so as to retrieve and load up any pertinent Storefront Gateway User details (e.g., retrieve all of a specified User’s accounts, groups, etc).

Error Codes

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

HTTP Status	Type	Storefront Gateway error code	Description
401	operation error	user-profile-locked	The user’s profile is locked.
401	operation error	authentication-required	One or more of the below 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 an MFA code, but the code provided was invalid.
Parent topic:Process APIs