Skip to main content

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.

info

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.

note

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.

note

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​

ParameterInTypeRequired / OptionalDescription
instanceIdpathstringrequiredThe ID of your Identity Cloud instance
userIdpathstringrequiredThe ID of the user

Request body​

ParameterTypeRequired / OptionalDescription
typeenumrequiredThe type of the email link Values: invitation, passwordReset
urlPrefixstringoptionalThe 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=

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\" }"

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."
}

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 failed due to an invalid access key.

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

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

Last updated on