Update Session
When an MFA challenge is needed, the partner responds to the initial POST /sessions request with one of the available MFA challenge responses. MX will collect the answers and provide them to the partner by making a PUT /sessions request. The partner can respond with a success response, another MFA challenge response, or an error response.
If the answers provided were correct and the MFA has been satisfied, a success response containing the session key should be returned.
If an additional MFA challenge is needed, another challenge can be returned.
If the answers provided were incorrect, a 401 (Unauthorized) error should be returned. Partners may also choose to send another challenge; MX does not limit the number of challenges that partners can return.
If you sent a list of MFA Options, the answer field will be assigned the option selected by the user.
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. |
answer | String | Yes | The answer to the challeng question returned in the POST /sessions response. |
options | Array | Required with MFA options. | A list of options the end user can choose from. |