The standard way to verify users identities with Tanker is to send a one-time-use, 8-digit code to their email address.

Send the identity verification email

To verify the user's email address, Tanker needs to send them an email. This is triggered by a call to https://api.tanker.io/verification/email, containing your own email template as well as all the information Tanker needs to send your email.

The request needs to be in the following format:

POST /verification/email

// JSON body:
{
    "app_id": <app_id>,
    "auth_token": <auth_token>,
    "email_data": {
        "subject": <subject>,
        "html": <html body>,
        "text": <text body>,
        "from_name": <from name>,
        "to_email": <recipient email address>,
        "to_name": <recipient name>
    }
}

The app ID and auth token are used to authenticate your server with the email verification service. They both can be found in your dashboard, in the app's settings.

The email's body should contain the TANKER_VERIFICATION_CODE placeholder. Tanker will use this placeholder to insert the verification code in the email.

See the API documentation for more details about this API.

Note

The user's email address is never stored in plain text on Tanker's servers. It is simply checked against the hashed value previously set up, and used once to send the email.

Setting up an email verification

Setting up an email for identity verification is done by using the registerIdentity() method with the email argument.

String email = "email@example.com"

if (status == Status.IDENTITY_REGISTRATION_NEEDED) {
  // Ask the application server to send a verification code via Tanker
  app.sendVerificationCode(email);

  // Wait for the user to input the verification code
  String verificationCode = app.promptUser("Enter your verification code:");

  // Register the identity
  tanker.registerIdentity(new EmailVerification(email, verificationCode)).get();
}

if (status == TKRStatusIdentityRegistrationNeeded) {

  // Ask the application server to send a verification code via Tanker
  [self.app sendVerificationCode:email];
  // Wait for the user to input the verification code
  NSString* verificationCode = [self.app promptUser:@"Enter your verification code:"];
  // Convert the email and verificationCode into a TKRVerification.
  TKRVerification* verification = [TKRVerification verificationFromEmail:email code:verificationCode];

  return [self.tanker registerIdentityWithVerification:verification completionHandler:^(NSError* err) {
    if (err == nil) {
      // do something
    }
  })];
}

if (status === Tanker.statuses.IDENTITY_REGISTRATION_NEEDED) {
  // Ask the application server to send a verification code via Tanker
  await app.sendVerificationCode(email);

  // Wait for the user to input the verification code
  const verificationCode = await app.promptUser('Enter your verification code:');

  // Register the identity
  await tanker.registerIdentity({ email, verificationCode });
}

Verifying the identity with the email

To later verify the user's identity using their email, send a verification email, ask the user to input the verification code and pass it to verifyIdentity() after starting the session:

if (status == Status.IDENTITY_VERIFICATION_NEEDED) {
      // Ask the application server to send a verification code via Tanker
      app.sendVerificationCode(emailAddress);

      // Wait for the user to input the verification code
      String verificationCode = app.promptUser("Enter your verification code:");

      // Verify the identity
      tanker.verifyIdentity(new EmailVerification(emailAddress, verificationCode)).get();
}

if (status == TKRStatusIdentityVerificationNeeded) {
  // Ask the application server to send a verification code via Tanker
  [self.app sendVerificationCode:email];
  // Wait for the user to input the verification code
  NSString* verificationCode = [self.app promptUser:@"Enter your verification code:"];
  // Convert the email and verificationCode into a TKRVerification.
  TKRVerification* verification = [TKRVerification verificationFromEmail:email code:verificationCode];

  return [self.tanker registerIdentityWithVerification:verification completionHandler:^(NSError* err) {
    if (err == nil) {
      // do something
    }
  })];
}

if (status === Tanker.statuses.IDENTITY_VERIFICATION_NEEDED) {
  // Ask the application server to send a verification code via Tanker
  await app.sendVerificationCode(email);

  // Wait for the user to input the verification code
  const verificationCode = await app.promptUser('Enter your verification code:');

  // Verify the identity
  await tanker.verifyIdentity({ email, verificationCode });
}

Update the user's email address

To update a user's email address, just call setVerificationMethod() with the new email and a corresponding verification code.

// Ask the application server to send a verification code via Tanker
app.sendVerificationCode(newEmail);

// Wait for the user to input the verification code
String verificationCode = app.promptUser("Enter your verification code:");

// Update the verification email
tanker.setVerificationMethod(new EmailVerification(newEmail, verificationCode)).get();

NSString* email = @"user@example.com";

// Ask your application server to send a verification code via Tanker
[self.app sendVerificationCode:email];
// Wait for the user to input the verification code
NSString* verificationCode = [self.app promptUser:@"Enter your verification code:"];
// Convert the email and verificationCode into a TKRVerification.
TKRVerification* verification = [TKRVerification verificationFromEmail:email code:verificationCode];

// Update the user's verification methods.
[self.tanker setVerificationMethod:verification
                 completionHandler:^(NSError* error) {
                 if (error == nil) {
                   // do something
                 }
              }];

function updateVerificationEmail(newEmail) {
  // Ask the application server to send a verification code via Tanker
  await app.sendVerificationCode(newEmail);

  // Wait for the user to input the verification code
  const verificationCode = await app.promptUser('Enter your verification code:');

  // Update the verification email
  await tanker.setVerificationMethod({ email: newEmail, verificationCode });
}