email-verification

Note: Link Based Verification is now Deprecated and only passcode now should be used.

email-verification is a service to support a verification flow that starts by creating a verification for an email address and sending out an email with verification link or a passcode.

Users can verify the email address by clicking on the link in the email, or typing in the passcode they received.

Endpoints are provided to trigger a verification email, verify email by clicking the link or entering passcode, and retrieve a verification status for a given email address.

How to build

Preconditions:

• mongod needs to be running for it:test

sbt test it:test

API

Path	Supported Methods	Description
/verification-requests	POST	Create a new verification request
/verified-email-check	POST	Check if email address is verified
/request-passcode	POST	*1 Generates a passcode and sends an email with the passcode to the specified email address
/verify-passcode	POST	*2 Verifies a passcode matches that stored against the email address
/verify-email	POST	Initiates the email-verification journey and returns frontend start URL
/verification-status/:credId	GET	Retrieves all the locked or verified emails against a cred ID

*represents sequence

Test Only Routes

Path	Supported Methods	Description
/test-only/passcodes	GET	Uses the session Id to return the email address(es) and passcode(s) associated with that 4hr session. Both the old link based POST /verify-email and newer POST /verify-email endpoints are supported, and the output will be additive for that session, so either POST endpoint will be operative with this test only endpoint

Example Response

{
  "passcodes": [
    {
      "email": "[email protected]",
      "passcode": "8bd63d50-8efd-4c12-82f3-ab6f6288bd02"
    },
    {
      "email": "[email protected]",
      "passcode": "e01c9c9f-5d8d-438d-9a4a-8b56ece8fa1b"
    }
  ]
}

Success Response

Status	Description
200	Retrieved one or more records

Failure Responses

Status	Description
404	No passcode found for sessionId
401	No session id provided

POST /verify-email

Initiates the email-verification journey. Sends passcode to email address if provided, then returns url to start frontend journey. If an email address is not provided then the user will be required to provide one on the frontend. The journeyId is returned to the calling service in the redirectUri. The calling service simply performs a redirect and does not need to extract any of the supplied redirectUri parameters, as the outcome callback GET endpoint uses a credId, not journeyId.

Example Request

{
  "credId":"0000000026936462",
  "continueUrl":"/plastic-packaging-tax/start",
  "origin":"ppt",
  "deskproServiceName":"plastic-packaging-tax",  // Optional, if absent then 'origin' will be used
  "accessibilityStatementUrl":"/accessibility",
  "pageTitle": "Plastic Packaging Tax", // Optional; will be displayed in the GOV.UK heading of the page
  "backUrl": "/back", // Optional; if provided, all pages will contain a "back" link to this URL
  "email": {
      "address":"[email protected]",
      "enterUrl":"/start" // user may get sent here if they cannot verify the provided email, e.g. they misspelled it
  }, // Optional, if absent then SI UI will prompt the User for the email address
  "lang":"en" // optional; en or cy; defaults to "en"
}

Example Response

{
   "redirectUri" : "/email-verification/journey/98fe3788-2d39-409c-b400-8f86ed1634ea?continueUrl=/plastic-packaging-tax/start&origin=ppt&service=plastic-packaging-tax"
}

Success Response

Status	Description
201	Journey successfully created

Failure Responses

Status	Description
400	Invalid request
401	Locked out or journey doesnt match session
500	Unexpected error
502	Email failed to send

GET /verification-status/:credId

Retrieves all the locked or verified emails against a cred ID. Only completed journeys will have a result, that can be one of the following states:

verified=true, locked=false
verified=false, locked=true

If locked=true, it is the responsibility of the calling service to handle a "locked" journey situation.

Example Request

GET /email-verification/verification-status/0000000026936462

Example Response

{
   "emails":[
      {
         "emailAddress":"[email protected]",
         "verified":true,
         "locked":false
      },
      {
         "emailAddress": "[email protected]",
         "verified":false,
         "locked":true
      }
   ]
}

Success Response

Status	Description
200	Retrieved one or more records

Failure Responses

Status	Description
400	Invalid request
404	No records found
500	Unexpected error

POST /verification-requests

Create a new verification request

Request body

{
  "email": "[email protected]",
  "templateId": "anExistingTemplateInEmailServiceId",
  "templateParameters": {
    "name": "Gary Doe"
  },
  "linkExpiryDuration" : "P1D",
  "continueUrl" : "http://some-continue.url"
}

The template identified by templateId must contain a parameter named verificationLink. One example is verifyEmailAddress. linkExpiryDuration is the validity in ISO8601 format. FYI, if you need to use/add a template, please speak to digital-contact team to get the templateId.

Please make sure that you validate your email address before making this request.

Success Response

Status	Description
201	Verification created successfully

Failure Responses

Status	Description	Code	Note
400	Invalid request	VALIDATION_ERROR
409	Email has already been verified	EMAIL_VERIFIED_ALREADY
400	Bad request to email, like template not found	BAD_EMAIL_REQUEST	This can also happen if the email address is notvalid, this can include leading and/or trailing spaces.
500	Unexpected error	UNEXPECTED_ERROR
502	Upstream service error	UPSTREAM_ERROR

POST /verified-email-check - DEPRECATED

Note: Deprecated for Security Reasons

Check if email address is verified or not, if verified return 200 with the email.

Request body

{
  "email": "[email protected]"
}

Success Response

Status	Description
200	Email is verified

Failure Responses

Status	Description	Code
404	Email not found / not verified	EMAIL_NOT_FOUND_OR_NOT_VERIFIED
500	Unexpected error	UNEXPECTED_ERROR
502	Upstream service error	UPSTREAM_ERROR

Response body

{
  "email": "[email protected]"
}

GET /test-only/passcodes

Retrieves the generated passcode for a given session ID provided in the headers

Example Request

GET /test-only/passcodes

X-Session-ID: SomeSessionId

Success Response

Status	Description
200	Found passcode against session ID

Failure Responses

Status	Description	Code
404	Passcode not found for given session ID	PASSCODE_NOT_FOUND_OR_EXPIRED
400	Session ID not provided in headers	BAD_PASSCODE_REQUEST

Response body

{
  "passcodes": [
    {
      "email": "[email protected]",
      "passcode": "ATERRT"
    }
  ]
}

POST /request-passcode

Generates a passcode and sends an email with the passcode to the specified email address. The serviceName field is inserted at the end of the email in the following sentence: From the [serviceName] service. The lang field must be either "en" or "cy", as English and Welsh are the only supported languages.

Request body

{
    "email": "[email protected]",
    "serviceName": "some service name",
    "lang": "en"
}

Success Response

Status	Description
201	Passcode is created and email is sent

Failure Responses

Status	Description	Code
409	Email already verified	EMAIL_VERIFIED_ALREADY
400	Upstream bad request sending email	BAD_EMAIL_REQUEST
401	SessionID not provided	NO_SESSION_ID
403	Max emails per session exceeded	MAX_EMAILS_EXCEEDED
502	Upstream error	UPSTREAM_ERROR

POST /verify-passcode

Verifies a passcode matches that stored against the email address and session id (that was sent to the email address)

Request body

{
    "passcode": "GHJKYF",
    "email": "[email protected]"
}

Success Response

Status	Description
201	Email is successfully verified
204	Email is already verified

Failure Responses

Status	Code	Description
401	NO_SESSION_ID	SessionID not provided
403	MAX_PASSCODE_ATTEMPTS_EXCEEDED	Max attempts per session exceeded
404	PASSCODE_NOT_FOUND	Passcode not found (or expired)
404	PASSCODE_MISMATCH	Incorrect passcode

Error response payload structure

Error responses are mapped to the following json structure returned as the response body with the appropriate http error status code. E.g.:

{
  "code": "PASSCODE_NOT_FOUND",
  "message":"Passcode not found"
}

or with details (optional):

{
  "code": "VALIDATION_ERROR",
  "message":"Payload validation failed",
  "details":{
    "obj.email": "error.path.missing"
  }
}

Generic errors

Payload validation errors are returning with 400 http status

{
  "code": "VALIDATION_ERROR",
  "message":"Payload validation failed",
  "details":{
    "obj.email": "error.path.missing"
  }
}

Not found errors are returning with 404 http status and a response body:

{
  "code":"NOT_FOUND",
  "message":"URI not found",
  "details": {
     "requestedUrl":"/email-verification/non-existent-url"
  }
}

Unexpected errors are returning with 500 http status and a response body:

{
  "code":"UNEXPECTED_ERROR",
  "message":"An unexpected error occured"
}

upstream errors are returning with 502 http status and a response body:

{
  "code":"UPSTREAM_ERROR",
  "message":"POST of 'http://localhost:11111/send-templated-email' returned 500. Response body: 'some-5xx-message'"
}

License

This code is open source software licensed under the Apache 2.0 License