Integrate with the KWS API

How to call the KWS API to trigger the parent verification flow for your product.

4 mins to read

To trigger the PV service flow, your product needs to call the send-parent-email API endpoint.

Get the API integration details

To call the KWS API, you need certain data items to enable access and authentication.

  1. In the Integration information tab, copy these details:

    Integration details

    Click image for full size.

  2. In the Parent Verification tab, copy these details:

    • Webhook secret code - Used to sign the payload to ensure it is a genuine call from KWS.
    • Service API host URL - The URL where the PV service is located. API queries should be made against this URL.
    PV details

    Click image for full size.

NOTE: Each product has both Test and Production credentials. Ensure you are using the correct set.

Collect the user details

You must configure your product’s interface to collect the following:

  • Parent's email address.
  • Child's location. This can be either:
    • a ISO 3166-1 alpha-2 code. For example, 'US', 'GB', 'CA'.
    • a recognised ISO 3166-2 subdivision. For example, 'US-CA', 'GB-ENG', 'CA-BC'.
  • Parent's language. This is the language that KWS uses for emails and verification screens presented to the parent. For example, ‘en’, ‘de’, ‘ja’. For the full list of supported languages, see Localizing the PV service.

Call the send-parent-email endpoint

Configure your product to send the collected parent's email address, child's location, and parent's language to KWS via an authenticated API call to the send-parent-email endpoint.

Rate limiting

Rate limiting is fixed to 10 requests per hour per unique parent email address.

User agent request header

All requests to the KWS API must include a user-agent header containing a non-empty string that identifies your client and/or HTTP library. Failure to do so will result in a “Request blocked” 403 response.

Authentication via the Developer Access token

API calls must be authenticated via a Bearer token called the "Developer Access token".

Obtain a Developer Access token from the KWS authentication service via a client_credentials OAuth grant from the token endpoint, using the Product client ID and Product API key (client secret) available from the Integration information tab.

NOTE: These credentials and tokens must remain confidential and must not be passed to client applications.

To obtain a token:

NOTE: Developer access tokens have a short expiry time, which is subject to change dynamically depending on usage patterns. The response to the oauth token request tells you how long the token is valid for (via expires_in, which is measured in seconds). When the token expires, you will receive 401 responses to API calls. You should obtain a new access token as described above and retry your request.

API call retry behavior

Any system integrating with the KWS API should implement a retry mechanism for API calls. If a retry mechanism is implemented, it must perform exponential backoff and conform to any rate-limiting headers sent from API calls.

The KWS-managed flow

After you call the KWS API, KWS manages the entire verification flow:

  1. KWS sends an email to the provided parent email address, asking the parent to confirm their identity.
  2. The parent clicks the link in the email to initiate the verification flow.
  3. KWS presents the parent with a web-based interface where they can enter their verification credentials. Depending on the child’s location and which verification methods you choose to present to the parent, different verification methods are available.
  4. On successful verification:

    • KWS sends the 'parent-verified' event back to your system using the webhook that you configured:

    • A hash of the parent’s email address is stored in the KWS ParentGraph. This enables KWS to determine if the parent is pre-verified the next time they encounter the PV service.

      Pre-verified parents do not have to provide verification credentials. ‘Pre-verified’ means the parent’s hashed email address is included in the ParentGraph, and the parent has been previously verified by the KWS PV service using a verification method which is (or was, at the time of verification) enabled for the product being accessed.

    • KWS sends a confirmation email to the parent, informing them that they have been successfully verified and added to the ParentGraph. (The email also contains a link to opt out of the ParentGraph.) In the case of payment-based verification methods, the email includes details about authorization, capture, and refunds, depending on the requirements in the child's country.

    • If you provided a Redirect URL in the Developer Portal, KWS redirects the parent to that URL. Otherwise, KWS displays a verification success message within the PV service web page.

See the PV service use case for examples of the emails and webviews that KWS presents to the parent.

Next step

Apply your own custom branding to the PV service.