Create email link
The endpoint provides the functionality to create an email link for a user for the following actions:
An email link is composed of a URL prefix and a ticket. The ticket is used to authenticate the user and can only be used once. A user can only have one email link at a time.
Use Verify email link ticket endpoint to authenticate a user with an email link ticket.
User invitation
Creates an invitation email link for a user. Upon creation, the user is notified with an email according to the configured invitation email template. The invitation email contains a personified URL link for the user to complete the signup.
An invitation e-mail link can only be created for users who have not yet completed the signup.
Password reset
Creates a password reset email link for a user. Upon creation, the user is notified with an email according to the configured password reset email template. The password reset email contains a personified URL link to set a new password.
A password reset email link can only be created for users who have already completed the signup.
HTTP request
POST https://$instanceId.id.nevis.cloud/nevis/api/v1/users/$userId/email-link
Parameters
| Parameter | In | Type | Required / Optional | Description |
|---|---|---|---|---|
instanceId | path | string | required | The ID of your Identity Cloud instance |
userId | path | string | required | The ID of the user |
Request body
| Parameter | Type | Required / Optional | Description |
|---|---|---|---|
type | enum | required | The type of the email link Values: invitation, passwordReset |
urlPrefix | string | optional | The base of the email link within the notification email Invitation default: https://$instanceId.id.nevis.cloud/account/invite/?x= Password reset default: https://$instanceId.id.nevis.cloud/account/pwreset/?x= |
Example user invitation email link request
Set the user ID and type. Optionally set a value for the URL prefix.
userId=your-user-id-123 \
type=invitation \
urlPrefix=https://your-company.com/?invitation=
curl --request POST "https://$instanceId.id.nevis.cloud/nevis/api/v1/users/$userId/email-link" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $accessKey" \
--data "{ \"type\" : \"$type\", \"urlPrefix\" : \"$urlPrefix\" }"
Example password reset email link request
Set the user ID and type. Optionally set a value for the URL prefix.
userId=your-user-id-456 \
type=passwordReset \
urlPrefix=https://your-company.com/?passwordReset=
curl --request POST "https://$instanceId.id.nevis.cloud/nevis/api/v1/users/$userId/email-link" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $accessKey" \
--data "{ \"type\" : \"$type\", \"urlPrefix\" : \"$urlPrefix\" }"
HTTP response
On success
HTTP/1.1 201 is returned if the email link is successfully created.
The response has the following additional header Location, containing the userId of the user:
https://$instanceId.id.nevis.cloud/nevis/api/v1/users/$userId/email-link
On missing user
HTTP/1.1 404 is returned with an error message if the user with the given userId is not found.
Example response
{
"error": "User with id: cdc891da-51ea-11ec-bf63-0242ac130002 cannot be found."
}
On email link exists
HTTP/1.1 422 is returned with an error message if the user with the given userId already has an email link.
Example response
{
"error": "User with id: 45843d01-c90a-4f2f-9cc1-3f9940b5d552 already has an email-link."
}
On failure
HTTP/1.1 401 is returned if the authorization fails due to an invalid access key.
HTTP/1.1 422 is returned if invalid request content is given.
HTTP/1.1 500 is returned if an unexpected error occurs.