Create Session
Sessions are created by making an POST request to the sessions endpoint. When creating a session, the request body will contain either a userkey or a login and password.
If the member could be authenticated with the provided credentials, a session key should be returned. If an MFA challenge is needed, an MFA challenge response should be returned.
If the member could not be authenticated with the provided credentials, a 401 (Unauthorized) error should be returned.
If a userkey is provided with the success response, it will be stored and used by MX as a credential for that user in future requests. This mechanism allows a partner to initially authenticate a user with a login, password, and MFA, then use the userkey in future sessions.
If MX receives a 401 error on a request with a userkey, it will be assumed that the userkey has become invalid. MX will remove the userkey and retry the authentication with the login and password. This allows a partner to invalidate a userkey to force reauthenication if needed.
Session Fields
| Field | Data Type | Required? | Definition |
|---|---|---|---|
key | String | Yes | The unique key for the session, used in all future MX requests. |
userkey | String | Required with userkey authentication. | This unique value is sent to the partner's MDX On Demand service to authenticate an aggregation request for a specific user. It is the preferred credential over login/password. |
challenges | Array | Required with MFA questions or MFA options. | A list of challenges to be answered by the end user. |
Challenge Fields
| Field | Data Type | Required? | Definition |
|---|---|---|---|
id | String | Yes | The unique identifier for the challenge. |
question | String | Yes | Human-readable text with the question the end user must answer. |
options | Array | Required with MFA options. | A list of options the end user can choose from. |