Complete Login

post/auth/login-complete

Complete a login sequence to obtain access and refresh tokens, and cardholder account id. The login sequence is initialized by Initiate Login or Sign Up. For more details, see Authentication.

With multi-factor authentication (MFA), a response can return a nextStep instead of credentials. Act on the next step and call Complete Login again with the same loginRequestId, until the response returns credentials. MFA adds two calls after the one carrying the signature: one to select the MFA method, and one to submit the MFA code.

Request

Query Parameters

mfabooleandefault: false
Opt in to multi-factor authentication. Only read on the call carrying the signature. When the account has a verified phone or email, the response returns a nextStep instead of credentials.

Body application/json

One of

loginRequestIdstringrequired
The unique identifier of the login request.
signaturestringrequired
The signature of the challenge.

loginRequestIdstringrequired
The unique identifier of the login request.
mfaMethodstringrequired
Allowed values:phoneemail
MFA method of the option selected from the mfaOptions of a select-mfa-method next step.
mfaDestinationstringrequired
Full phone number in E.164 format, or full email address. Must match the verified destination behind the masked option.

loginRequestIdstringrequired
The unique identifier of the login request.
mfaCodestringrequired
One-time code sent to the selected MFA method.

Response

Successful operation.

Body application/json

One of

accessTokenstring
The access token that will be used for subsequent authenticated requests.
refreshTokenstring
JWT that is used to request a new access token. Refresh tokens are valid for 30 days.
cardholderAccountIdstring
The unique identifier of the cardholder.

loginRequestIdstring
The unique identifier of the login request.
nextStepobject
Step to complete before calling Complete Login again with the same loginRequestId.
One of
typestring
Allowed values:select-mfa-method
Type of the next step.
expiresAtstring<date-time>
Time after which the login sequence must be restarted.
mfaOptionsobject[]
Verified MFA options of the account, with masked destinations. Select one by sending its mfaMethod and full mfaDestination.
Items
methodstring
Allowed values:phoneemail
MFA method.
maskedDestinationstring
Masked phone number (country code and last 4 digits) or masked email address.

INVALID_SIGNATURE Invalid signature.

CHALLENGE_EXPIRED Challenge expired.

LOGIN_STEP_INVALID Request body does not match the login request's current step.

MFA_METHOD_MISMATCH Destination does not match a verified MFA option of that method.

MFA_CODE_INVALID Invalid MFA code.

MFA_CODE_EXPIRED MFA code expired. Restart the login sequence.

MFA_ATTEMPTS_EXCEEDED Too many failed MFA attempts on this login request. Restart the login sequence.

Body application/json

statusCodeintegerrequired
statusNamestringrequired
errorCodestringrequired
reasonstring

Example

Example Request

Server

curl https://api.immersve.com/auth/login-complete \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginRequestId": "49ae8f3a3928491",
  "signature": "0xa91fd3b8bf..."
}'

curl https://api.immersve.com/auth/login-complete \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginRequestId": "49ae8f3a3928491",
  "mfaMethod": "phone",
  "mfaDestination": "+64211231234"
}'

curl https://test.immersve.com/auth/login-complete \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginRequestId": "49ae8f3a3928491",
  "signature": "0xa91fd3b8bf..."
}'

curl https://test.immersve.com/auth/login-complete \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginRequestId": "49ae8f3a3928491",
  "mfaMethod": "phone",
  "mfaDestination": "+64211231234"
}'

Example Response

{
  "accessToken": "eyJhbGasddweUzI1NiIsI...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsI...",
  "cardholderAccountId": "29097f50d221858223a17633e36716f9"
}

{
  "loginRequestId": "49ae8f3a3928491",
  "nextStep": {
    "type": "select-mfa-method",
    "expiresAt": "2026-10-15T08:20:00Z",
    "mfaOptions": [
      {
        "method": "phone",
        "maskedDestination": "+64 *****1234"
      }
    ]
  }
}

{
  "loginRequestId": "49ae8f3a3928491",
  "nextStep": {
    "type": "submit-mfa-code",
    "expiresAt": "2026-10-15T08:25:00Z",
    "mfaOption": {
      "method": "phone",
      "maskedDestination": "+64 *****1234"
    }
  }
}

{
  "statusCode": 403,
  "statusName": "Forbidden",
  "errorCode": "FORBIDDEN",
  "reason": "Unauthorized"
}