Rate this page

Validated Email Addresses

An account management application can use the validatedEmailAddresses SCIM sub-resource to deliver a one-time code to confirm a user’s ownership of an email address. Once this is done, the email address may be used to receive one-time password codes as an authentication factor.

The following table describes the fields of an email validation request.

Field Type Required? Description
schemas array yes The SCIM schema of the email verification request. Always has the value urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest.
meta complex no Will always contain a resourceType sub-attribute with the default value Email Address Validator. Will always contain a location attribute with the validated email address resource’s canonical URI.
attributePath string yes The SCIM attribute path containing the email address. For example, emails[type eq "home"].value or secondFactorEmail.
attributeValue string yes The email address.
verifyCode string yes A verification code to submit for confirmation.

The following table describes the fields of an email validation response.

Field Type Provided? Description
schemas array always The SCIM schema of the password resource. Always has the value urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest.
meta complex always Will always contain a resourceType sub-attribute with the value Email Address Validator. Will always contain a location attribute with the validated email address resource’s canonical URI.
attributePath string always The SCIM attribute path containing the email address. For example, emails[type eq "home"].value or secondFactorEmail.
attributeValue string The email address.
validated boolean Whether the current email address was successfully validated.
validatedAt datetime The last time the current email address was successfully validated.
codeSent boolean Whether a verification code was sent and is pending validation.

Retrieve a user’s validated email address states for all configured attribute paths

GET /scim/v2/Users/{id}/validatedEmailAddresses

GET /scim/v2/Me/validatedEmailAddresses

The Data Governance Broker administrator may configure one or more SCIM attribute paths to identify an email address that may be validated. A GET to a user’s root validatedEmailAddresses sub-resource will return a list response containing zero or more matching resources corresponding to these attribute paths. The validated field of each resource indicates if that email address has already been validated. The validatedAt field of each resource, if present, indicates when the email address was validated.

Example request:

GET /scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 598
Content-Type: application/scim+json
Date: Mon, 01 Aug 2016 14:09:37 GMT

{
    "Resources": [
        {
            "attributePath": "secondFactorEmail",
            "attributeValue": "rick.deckard@lapd.gov", 
            "id": "secondFactorEmail",
            "meta": {
                "location": "https://example.com:443/scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses/emails%5Btype%20eq%20%22other%22%5D.value", 
                "resourceType": "Email Address Validator"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest"
            ], 
            "validated": true, 
            "validatedAt": "2016-08-01T14:03:21.252Z"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 1
}

Retrieve a user’s validated email address states for a specific attribute path

GET /scim/v2/Users/{id}/validatedEmailAddresses/{attributePath}

GET /scim/v2/Me/validatedEmailAddresses/{attributePath}

The Data Governance Broker administrator may configure one or more SCIM attribute paths to identify an email address that may be validated. A client can perform a GET to a user’s validatedEmailAddresses sub-resource using an attribute path as the sub-resource ID. The validated field of the response will indicate if that email address has already been validated. The validatedAt field, if present, indicates when the email address was validated.

The following example shows the validation status for an email address with the attribute path secondFactorEmail.

Example request:

GET /scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses/secondFactorEmail HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com:443

Example response:

HTTP/1.1 200 OK
Content-Length: 500
Content-Type: application/scim+json
Date: Mon, 01 Aug 2016 14:09:49 GMT

{
    "attributePath": "secondFactorEmail",
    "attributeValue": "rick.deckard@lapd.gov", 
    "id": "secondFactorEmail",
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses/emails%5Btype%20eq%20%22other%22%5D.value", 
        "resourceType": "Email Address Validator"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest"
    ], 
    "validated": true, 
    "validatedAt": "2016-08-01T14:03:21.252Z"
}

Validate a user’s email address

A web application may validate a user’s email address using a special multi-step flow.

Deliver a validation code

POST /scim/v2/Users/{id}/validatedEmailAddresses

POST /scim/v2/Me/validatedEmailAddresses

Submitting a POST request to a user’s validatedEmailAddresses sub-resource will cause a verification code to be delivered to the email address specified in the request. The Data Governance Broker’s response will include a special temporary resource representing a stateful verification request, with the request state encoded in the resource ID. The response will use a 201 Created status code, with the temporary state URI provided in the Location header and meta.location attribute. This URI will be used in the next step when confirming the verification code provided by the user.

Example request:

POST /scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 331
Content-Type: application/scim+json
Host: example.com:443

{
    "attributePath": "secondFactorEmail",
    "attributeValue": "rick.deckard@lapd.gov", 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest"
    ]
}

Example response:

HTTP/1.1 201 Created
Content-Length: 824
Content-Type: application/scim+json
Date: Mon, 01 Aug 2016 13:59:17 GMT
Location: https://example.com:443/scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses/AScqzbX56d-oaI0tbtQrvsI5IyjcAAAAAAAAAADFRUel6V0yY4DTbmmcgjRFT-qtBy4wU6d6iaWtwPBCiBWrJm4ASsCeMvciCVuUEweLcD-oKK7qk6icybO12QXFD5AXuH0HF5VuSYlkXsj6wnedhS1Q-U2DNaBjw8GpifU4aYd4pz_tXeBbYoQh8Kb4XDzeyx8nvzoMU7G5iaj7VQ

{
    "attributePath": "secondFactorEmail",
    "attributeValue": "rick.deckard@lapd.gov", 
    "codeSent": true, 
    "id": "AScqzbX56d-oaI0tbtQrvsI5IyjcAAAAAAAAAADFRUel6V0yY4DTbmmcgjRFT-qtBy4wU6d6iaWtwPBCiBWrJm4ASsCeMvciCVuUEweLcD-oKK7qk6icybO12QXFD5AXuH0HF5VuSYlkXsj6wnedhS1Q-U2DNaBjw8GpifU4aYd4pz_tXeBbYoQh8Kb4XDzeyx8nvzoMU7G5iaj7VQ", 
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses/AScqzbX56d-oaI0tbtQrvsI5IyjcAAAAAAAAAADFRUel6V0yY4DTbmmcgjRFT-qtBy4wU6d6iaWtwPBCiBWrJm4ASsCeMvciCVuUEweLcD-oKK7qk6icybO12QXFD5AXuH0HF5VuSYlkXsj6wnedhS1Q-U2DNaBjw8GpifU4aYd4pz_tXeBbYoQh8Kb4XDzeyx8nvzoMU7G5iaj7VQ", 
        "resourceType": "Email Address Validator"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest"
    ], 
    "validated": false
}

Confirm a delivered validation code

PUT /scim/v2/Users/{id}/validatedEmailAddresses/{verificationId}

PUT /scim/v2/Me/validatedEmailAddresses/{verificationId}

If the result of the POST request above was successful, then the application can prompt the user to provide the verification code received at his or her email address. The application should then make a PUT request to the new URI from the previous POST response, including the verification code provided by the user in the verifyCode field.

If the verification code is confirmed by the Data Governance Broker, then a 200 OK response will be returned, and the application may consider the email address verified. If not — either because an invalid code was submitted or the code has expired — a 400 Bad Request response will be returned with a scimType value of invalidValue.

The following is an example of a successful request and response.

Request:

PUT /scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses/AScqzbX56d-oaI0tbtQrvsI5IyjcAAAAAAAAAADFRUel6V0yY4DTbmmcgjRFT-qtBy4wU6d6iaWtwPBCiBWrJm4ASsCeMvciCVuUEweLcD-oKK7qk6icybO12QXFD5AXuH0HF5VuSYlkXsj6wnedhS1Q-U2DNaBjw8GpifU4aYd4pz_tXeBbYoQh8Kb4XDzeyx8nvzoMU7G5iaj7VQ HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 941
Content-Type: application/scim+json
Host: example.com:443

{
    "attributePath": "secondFactorEmail",
    "attributeValue": "rick.deckard@lapd.gov", 
    "codeSent": true, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest"
    ], 
    "validated": false, 
    "verifyCode": "037161"
}

Response:

HTTP/1.1 200 OK
Content-Length: 500
Content-Type: application/scim+json
Date: Mon, 01 Aug 2016 14:03:21 GMT

{
    "attributePath": "secondFactorEmail",
    "attributeValue": "rick.deckard@lapd.gov", 
    "id": "secondFactorEmail",
    "meta": {
        "location": "https://example.com:443/scim/v2/Users/866f5d93-272f-43e7-9dad-07cec9f5c935/validatedEmailAddresses/emails%5Btype%20eq%20%22other%22%5D.value", 
        "resourceType": "Email Address Validator"
    }, 
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:EmailValidationRequest"
    ], 
    "validated": true, 
    "validatedAt": "2016-08-01T14:03:21.252Z"
}

The following example shows the response to a request that used an invalid code:

HTTP/1.1 400 Bad Request
Content-Length: 161
Content-Type: application/scim+json
Date: Mon, 01 Aug 2016 14:03:21 GMT

{
    "detail": "The provided code does not match the delivered code", 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ], 
    "scimType": "invalidValue", 
    "status": 400
}