Integrate with the KWS API

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

The KWS API specification can be found here.

Get integration details

To integrate with the KWS API, you need certain data items to enable access and authentication. To find them:

  1. Navigate to the KWS Developer Portal's Dashboard.

  2. Select the required product. Below the product's Basic information, you can view and copy the following integration details: integration_info.png

Initiate the Parent Verification flow

  1. Collect the following details in your own interface:

    • Parent's email address

    • Kid's location

    • Parent's language

  2. Send these details to KWS via an authenticated API call to the send-parent-email endpoint.

From this point, the entire flow is managed by KWS:

  1. KWS sends an email to the provided address to confirm the identity of the parent and initiate the verification flow. KWS uses a web-based interface to perform the verification.

  2. On successful verification, KWS sends a notification email to the parent and redirects them back to your interface. The redirect URL is configured by you in the Developer Portal.

Authentication

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

Developer Access token

A Developer Access token is obtained from the KWS authentication service using a client_credentials OAuth grant from the token endpoint, using the client ID and secret available from the Developer Portal. These credentials and tokens must remain confidential and must not be passed to client applications.

NOTE: Each product has both Test and Production credentials.

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 as per the OAuth2 specification.

Retry Behaviour

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.

Retry behaviour is dependent on the status code your server returns to the POST request:

Status Codes

Status code

Behaviour

100 to 399

Call assumed to be successful.

400 to 499

Permanent failure. Call will be logged as failed and not retried.

500+, timeout (3 seconds) or network error

Transient failure. The call will be retried after 1, 5, 15, and 30 minutes, and then after 1, 6, and 24 hours. If the final retry fails (status code 400+) then the call will be logged as failed.

Redirect URL

This is the URL that KWS redirects the parent to upon successful or ultimate failure of verification. It is configured in the Developer Portal.

Webhooks

KWS notifies your systems of events via webhook calls. Webhooks are configured in the Developer Portal.

Successful verification event

KWS sends the parent-verified event upon successful verification of a parent:

Body
{
  "name": "parent-verified",
  "time": "ISO8601 timestamp",
  "orgId": "uuid",
  "productId": "uuid",
  "environmentId": "uuid",
  "payload": {
    "parentEmail": "...",
    "externalPayload": "...",
    "status: {
      "verified": true,
      "transactionId": "..."
    }
  }
}
Tags