Verify email link ticket

The endpoint provides the functionality to verify the email link ticket of a user. The endpoint supports password reset and invitation email link ticket verification.

The email link URL sent to the user by email contains a urlPrefix, and an email link ticket that you can use for verification. Example password reset email link URL:

https://your-company.com/account/pwreset/?x=H%2ED2dLDaXTi16RWk5C2oOA~sT83MMdj9kd_LkM_kQLrm_cq3lQ%2ENjcOy%2EweGirQUQcO6G8HXe8ydsb04rxyWQBWoewYBlxTn%2ECZ0h7RqcIH_6yf_Kf_TxxlJxl54vDg36A

HTTP request

POST https://$instanceId.id.nevis.cloud/nevis/api/v1/auth/email-link

Parameters

Parameter	In	Type	Required / Optional	Description
instanceId	path	string	required	The ID of your Identity Cloud instance

Request body

Parameter	type	Required / Optional	Description
ticket	string	required	The ticket value

Example request

Set the ticket value.

ticket=H%2ED2dLDaXTi16RWk5C2oOA~sT83MMdj9kd_LkM_kQLrm_cq3lQ%2ENjcOy%2EweGirQUQcO6G8HXe8ydsb04rxyWQBWoewYBlxTn%2ECZ0h7RqcIH_6yf_Kf_TxxlJxl54vDg36A

curl --request POST "https://$instanceId.id.nevis.cloud/nevis/api/v1/auth/email-link" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $accessKey" \
  --data "{ \"ticket\" : \"$ticket\" }"

HTTP response

On successful verification

HTTP/1.1 200 is returned if the email link ticket is successfully verified. The response contains detailed information about the verification result.

Parameter	In	Description
loginId String	body	The login ID (username) of the user
userId UUID	body	The identifier of the user
login.status String	body	Verification result status Values succeeded, failed
login.failedReason String	body	Reason of verification failure Values invalidTicket, expiredTicket, malformedTicket, userBlocked

Example succeeded response

{
  "loginId": "[email protected]",
  "userId": "4a5e7346-488b-46f9-914f-79ddb1131e0b"
  "login" : {
    "status": "succeeded"
  }
}

Example invalid response

This response is returned when the email link was already used.

{
  "login" : {
    "status": "failed"
    "failedReason": "invalidTicket"
  }
}

Example expired response

This response is returned when the email link could be valid, but has already expired.

{
  "login" : {
    "status": "failed"
    "failedReason": "expiredTicket"
  }
}

Example malformed response

This response is returned when the email link was an incorrect value.

{
  "login" : {
    "status" : "failed"
    "failedReason": "malformedTicket"
  }
}

Example blocked response

This response is returned when the user that this email link is attached to is blocked, regardless of the validity of the email link.

{
  "loginId": "[email protected]",
  "userId": "4a5e7346-488b-46f9-914f-79ddb1131e0b"
  "login" : {
    "status": "failed"
    "failedReason": "userBlocked"
  }
}

On failure

HTTP/1.1 401 is returned if the authorization fails due to an invalid access key or blocked user.

HTTP/1.1 422 is returned if invalid request content was given.

HTTP/1.1 500 is returned if an unexpected error occurred.