Password Reset Flow API¶

Reviewing the Messaging API documentation will be helpful as the information about value specifiers, SendGrid integration, etc applies here as well.

A password reset flow allows you to offer password reset functionality that’s integrated into your app with minimal effort. Accounts can have multiple flows active at once, but typical usage will just have one flow, so examples will assume a single flow. Creating a flow is done up front by an administrator, and the flow is then used many times by various users.

A typical sequence of user interactions might be:

A user forgets their password and finds their way to your “Forgot password” UI. After the user enters their username, your app logic makes an API call to TrueVault to start a password reset flow for that username. Here, using a hardcoded flow id is typically a reasonable choice because there is only one flow.
TrueVault sends the user an email with a link via SendGrid. The link contains a single-use token that allows that specific user to reset their password for a limited time.
The user clicks the link, and in the resulting web page, enters in their new password information. Using credentials extracted from the link, JavaScript in that web page makes an API call to TrueVault, and the user’s password is updated accordingly.

A password reset flow contains all the configuration needed to make the above work, namely the SendGrid API key and template ID to use for sending email and value specifiers for the email body and the email address.

To quickly build a fully functional flow, complete with sample code, see the admin console.

Create a password reset flow¶

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png

POST /v1/password_reset_flows¶

Create a new password reset flow.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` Content-Type – `application/json`
Request JSON Object:
	name(req’d) (string) – A name for this flow for your own organizational purposes. sg_template_id(req’d) (string) – The SendGrid template ID to use when sending email for this flow. sg_api_key(req’d) (string) – The SendGrid API key to use when sending email for this flow. user_email_value_spec(req’d) (object) – object(req’d) The Value Specifier representing the to email address. As with the Email API, using a literal value specifier is invalid for the to address. from_email_value_spec(req’d) (object) – The Value Specifier representing the from email address. This field does permit using a literal, and that is the typical choice. substitutions(req’d) (object) – A mapping from names to value specifiers. These behave just like the substitutions in the Messaging API. These will be applied to the email that is sent to a user when they enter the flow.

Example Request

curl https://api.truevault.com/v1/password_reset_flows \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
         "name": "Normal user password reset",
         "sg_template_id": "00000000-0000-0000-0000-000000000000",
         "sg_api_key": "secret",
         "user_email_value_spec": {"system_field": "username"},
         "from_email_value_spec": {"literal_value": "info@your-company.com"},
         "substitutions": {
            "{{FIRST_NAME}}": {"user_attribute": "first_name"},
            "{{APPOINTMENT_TIME}}": {"literal_value": "3:30"},
            "{{DASHBOARD_URL}}": {"literal_value": "http://dashboard.example.com"}
         }
    }'

Example Success Response

The response contains the relevant data for the newly created flow (excluding the SendGrid API key).

{
    "password_reset_flow": {
        "id": "8a100cfa-02ba-49c6-b706-4b54105eb16b",
        "name": "Normal user password reset",
        "sg_template_id": "00000000-0000-0000-0000-000000000000",
        "substitutions": {
            "{{FIRST_NAME}}": {"user_attribute": "first_name"},
            "{{APPOINTMENT_TIME}}": {"literal_value": "3:30"},
            "{{DASHBOARD_URL}}": {"literal_value": "http://dashboard.example.com"}
        },
        "user_email_value_spec": { "system_field": "username" },
        "from_email_value_spec": {"literal_value": "info@your-company.com"}
    },
    "result": "success",
    "transaction_id": "4545cc5a-e9cc-4866-b835-0d62d9fdd12f"
}

Example Error Response

If the request is invalid or the encounters an error, the HTTP status will be 4XX or 5XX as appropriate and the response JSON will include an error object describing the problem. For instance, when providing a malformed substitutions object, the result might be something like:

{
    "error": {
        "code": "GLOBAL.BAD_INPUT_PARAMETER",
        "message": "Invalid substitutions: [] is not of type 'object'",
        "type": "invalid_request_error"
    },
    "result": "error",
    "transaction_id": "46f5389e-d35e-4277-b719-11f58a5bec21"
}

Send a password reset email¶

POST /v1/password_reset_flows/(string: flow_id)/email¶

Send a password reset email to a user in a particular password reset flow.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` Content-Type – `application/json`

Since almost all the relevant data is already stored in the flow itself, this endpoint only has two parameters

Request JSON Object:
Parameters:	flow_id – string(req’d) supplied as a URL path parameter.
	username(req’d) (string) – A field in the JSON object POSTed to the URL.

The SendGrid API and template ID for the specified flow are used to send an email. All configured substitutions will be evaluated. Two more substitutions are supplied automatically:

{{TV_PW_RESET_HTTP_BASIC_AUTHN}}: authentication info used to make the password reset API request

{{TV_PW_RESET_USER_ID}}: the user id whose password is to be reset

The email sent will allow the user to change their password once, and will expire after 4 hours.

Example Request

curl https://api.truevault.com/v1/password_reset_flows/00000000-0000-0000-0000-000000000000/email \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
         "username": "alex"
    }'

Example Success Response

To avoid username enumeration attacks, no extra response data is provided when an email is successfully sent. (The same response is provided when the username is invalid.)

{
    "result": "success",
    "transaction_id": "4545cc5a-e9cc-4866-b835-0d62d9fdd12f"
}

Example Error Response

If the request fails because of an issue with email delivery, the HTTP status will be 4XX or 5XX as appropriate and the response JSON will include an error object describing the problem. For instance, when the SendGrid API key is invalid, the result might be something like:

{
    "error": {
        "code": "EMAIL.SEND_ERROR",
        "message": "Error sending email",
        "provider_error": {
            "errors": [
                {
                    "field": null,
                    "help": null,
                    "message": "The provided authorization grant is invalid, expired, or revoked"
                }
            ]
        },
        "type": "request_failed"
    },
    "result": "error",
    "transaction_id": "00ae1f88-0fde-4a77-830f-39dfe89da379"
}

List Password Reset Flows¶

GET /v1/password_reset_flows¶

Returns password reset flows in account.

Example Request

curl https://api.truevault.com/v1/password_reset_flows \
    -u [API_KEY | ACCESS_TOKEN]:

Example Success Response

{
    "password_reset_flows":
        [
            {
                "created_at": "2018-04-03T17:29:02.289000Z",
                "from_email_value_spec": {"literal_value": "support@truevault.com"},
                 "id": "a3facc3d-9830-45f7-8df3-0518d6992b8c",
                 "linked_scoped_access_token_id": "d14eac1d-6818-45b2-9135-5d2401441398",
                 "name": "Default flow",
                 "sg_template_id": "ac79d4da-dce8-4601-82d2-942b57230323",
                 "substitutions": {"{{FIRST_NAME}}": {"user_attribute": "firstName"}},
                 "user_email_value_spec": {"system_field": "username"}
             }
         ],
     "result": "success",
     "transaction_id": "47165ba4-85f1-4791-a991-882afa5cb87a"
 }

Link a Scoped Access Token to a Password Reset Flow¶

POST /v1/password_reset_flows/(string: flow_id)/link_sat¶

Links a Password Reset Flow to the Scoped Access Token used to send “Forgot Password” emails.

This is the final step in the Password Reset Flow creation process.

Request Headers:
	Authorization – `API_KEY` or `ACCESS_TOKEN` or `SCOPED_ACCESS_TOKEN` Content-Type – `application/json`
Parameters:	flow_id – string(req’d) supplied as a URL path parameter.
Request JSON Object:
	scoped_access_token_id(req’d) (string) – The ID of the SAT to be linked

Example Request

curl https://api.truevault.com/v1/password_reset_flows/00000000-0000-0000-0000-000000000000/link_sat \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
         "scoped_access_token_id": "00000000-0000-0000-0000-000000000000"
    }'

Example Success Response

{
    "result": "success",
    "transaction_id": "4545cc5a-e9cc-4866-b835-0d62d9fdd12f"
}