What's the difference between ManagementClient.sendEmailVerification() and ManagementClient.tickets.verifyEmail()?

[morphatic]

Using node-auth0 to create an instance of a ManagementClient, there appear to be three ways to access the functionality needed to resend the email verification email to a newly signed up user:

// import the library
const { ManagementClient } = require('auth0')

// instantiate a client
const creds = {
  domain: 'example.auth0.com',
  clientId: 'MY_CLIENT_ID',
  clientSecret: 'MY_CLIENT_SECRET'
}
const client = new ManagementClient(creds)

// create a ticket to (re)send the email verification email

// METHOD #1
client.sendEmailVerification({ user_id: 'auth0|0123456789' }, res => {
  console.log(res.ticket)
}) 

// METHOD #2
client.tickets.verifyEmail({ user_id: 'auth0|0123456789' }, res => {
  console.log(res.ticket)
})

// METHOD #3
client.createEmailVerificationTicket({ user_id: 'auth0|0123456789' }, res => {
  console.log(res.ticket)
})

I’m confused about why there appear to be two ways to do this. Are these both essentially the same thing? According to the API docs, this endpoint will accept an object that has the following properties:

{
  "result_url": "https://example.com/callback",
  "user_id": "auth0|0123456789",
  "ttl_sec": 0,
  "includeEmailInRedirect": false
}

In the other docs, method #2 (and method #3) shows that it will accept more than just the user_id prop, but method #1 does not mention other props. Will all three methods accept all of the props?

Is one of these methods preferred above the othesr? Thanks!!!

[morphatic]

Note, my confusion also extends to the methods for changing a password and/or requesting an email with a link to a page where you can change your password:

// Method #1
client.createPasswordChangeTicket({ user_id: 'auth0|0123456789' }, cb)

// Method #2
client.tickets.changePassword({
  user_id: 'auth0|0123456789',    // either `user_id` OR `email`
  email: 'somebody@example.com',  // is required
  new_password: 'super_secret123!'
}, cb)

I’m confused both as to why both of these functions exist, and for method #2, why you would pass a new_password if this method just creates a password change ticket.

[morphatic]

tl;dr jump to solution

In answer to my first question above, here’s what I’ve discovered by reading through the source code:

1. client.createEmailVerificationTicket() (method 3) is simply a wrapper around client.tickets.verifyEmail() (method 2) and neither of these methods will actually send an email to the user. They return a verification link, that in turn, you would have to send to the user on your own (presumably via email). Both of these methods will accept all four of the parameters described above.
2. client.sendEmailVerification() (method 1) is a wrapper around client.jobs.verifyEmail(). These methods will actually send the verification email, but they only accept the user_id param, so you don’t have an opportunity to specify the redirect_url or other params. This turns out to be a problem, as I’ll describe below.

My goal when I asked these questions was to be able to provide a button within my SPA (Vue.js-based) that would send a request to my backend API that would, in turn, use the Auth0 Management API to re-send a verification email.

I was successfully able to resend the verification email, but when I clicked the link I got an error message: Failed Verification Email: invalid result url. When I checked the logs on the Auth0 Dashboard, the relevant data associated with the ticket was "resultUrl": "{{ application.callback_domain }}" which is what I have stored in my verification email template.

In production, this shouldn’t be a problem because I can hard code the correct URL. However in testing, I’d like to have the ability to redirect users to different URLs, e.g. https://testing.example.com/, by specifying the redirect_url along with the request. Instead, the logs indicate that the Application Name/client_id associated with the call to client.sendEmailVerification() was “All Applications”/my_global_client_id. The advanced global tenant settings don’t appear to have a way to set the redirect URL.

A bit more about my setup: under Dashboard > Applications, I have two applications setup–one for testing and one for production. The first URL under “Allowed Callback URLs” is set to the appropriate URL for each scenario. For the sunshine scenario (i.e. when a user doesn’t “lose” the email verification email) this works GREAT!! Clicking on the “confirm my account” link in the email verification email redirects users back to the correct version of my app.

Solution

I found this issue on the GitHub repo which suggested that all I needed to do was pass the appropriate client_id along with the API request. Now my code looks like:

client.sendEmailVerification({
  client_id: 'my_testing_or_production_app_client_id',
  user_id: 'auth0|0123456789'
}).then(/* ... */)

Now I can send my users a correct verification link regardless of whether they’re on the production or testing version of my app!

[konrad.sopala]

Thanks a lot for sharing it with the rest of community!