Integrate with the KWS API

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

The next step is to configure the call to 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.

In the Integration information tab, copy these details:

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.

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 Languages supported by KWS.

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.

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:

POST https://auth.kws.superawesome.com/auth/realms/kws/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: basic <base64 of client-id:client-secret>
Request:
grant_type=client_credentials&scope=verification
Response (OAuth2 Token Response):
{
"access_token": "..."
"refresh_token": "..."
}

NOTE: Developer access tokens have a short expiry time. The response to the oauth token request tells you how long the token is valid for (it is subject to change). Ensure you implement 'token refresh' in accordance with the OAuth2 specification.

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:

      Body
      {
      "name": "parent-verified",
      "time": "ISO8601 timestamp",
      "orgId": "uuid",
      "productId": "uuid",
      "environmentId": "uuid",
      "payload": {
          "parentEmail": "...",
          "externalPayload": "...",
          "status: {
              "verified": true,
              "transactionId": "..."
                   }
                 }
      }
    • 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.

Next step

Apply your own custom branding to the PV service.