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.

In the Integration information tab, copy these details:

Integration details

Click image for full size.

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:

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