API specification

Introduction

KWS provides an HTTP API for interfacing with the platform in order to create kid-safe apps. The API exposes functionality like managing user accounts & authentication, requesting permissions from parents and involving parents with the safety of their children via our Parent Portal.

Note

All KWS APIs use HTTPS protocol and JSON.

API Responses

The KWS API makes use of standard HTTP response codes in order to inform the client how the request was handled. Most importantly, a 2xx response denotes success, whereas 4xx or 5xx will mean there was an error of some kind and the request could not be processed.

Some examples of common response codes:

  • 2xx Success. The action has been carried out.
  • 400 Bad request. Expect to see a message in the response body explaining what was wrong with the request.
  • 401 Unauthorized. You must authenticate and pass a valid token in the request.
  • 403 Forbidden. The authenticated user does not have access to the intended action.
  • 404 Not found. Endpoint does not exist, or item not found.
  • 405 Method not allowed. Usually means the incorrect HTTP method was used.
  • 409 Conflict. For example, trying to register with a username that’s already in use.
  • 500 Unexpected error. We will have been notified and will rectify the issue.

API Authentication

All the endpoints will need a Bearer token in the HTTP Authorization header like this:

Authorization: Bearer {TOKEN}

Where {TOKEN} has to be replaced by the corresponding session token obtained in the OAuth authentication process. The token will have different permissions and will enable calling different endpoints depending on the client and the type of credentials used in the authentication flow. This is further explained in the next section: OAuth

OAuth Authentication

KWS follows OAuth2 core standard. In order to know about the basics of OAuth2, like understanding the different flows and the concept of scopes, please visit the following site: https://oauth.net/2/. The authorization flows that are supported are the following:

  • Client credentials flow: used in Backend to Backend interactions.
  • Authorization code flow: used to authenticate users with the single sign-on for websites.
  • Implicit flow: used to authenticate users with the single sign-on for websites without an API.

Note

After a bearer token has expired, using it in API call will result in a 401 error. It is the responsibility of the application to handle this by renewing the token in advance or by gracefully handling the 401 error and retrying the API call after getting a new valid token.

The bearer token

KWS bearer token uses the JSON Web Token standard. See https://jwt.io/ for more details on how JWTs work and for libraries you can use to decode them.

When using JWTs to interact with our APIs you will want to pay special attention to:

  • the token expiry time (we recommend that your applications check this before using our endpoints).
  • the scope property in the token payload (see the Scopes section below for more details).
  • the appId in the token payload. If you’re using a token with the user scope, this will indicate which of your KWS apps this token has access to.

Scopes

The available scopes for an authentication token are the following:

  • user: Scope that is specific to a user & app, and that allows you to read and update app data or request permissions. This token is received only after user authentication and is normally used in front-ends. (Note that the token payload contains an appId parameter which indicates which app it can access).
  • sso: Scope that allows you to authenticate on behalf of an app, activate a user with an app, or delete a user account. This scope is only necessary if you are building your own SSO application.
  • app: Scope that allows you to interact with or configure an application. It must be used in Backend to Backend API calls only and never exposed to any frontend.

Client credentials

This flow is used when a backend needs to interact with the KWS API directly.

Important

This authentication flow is only for backend-to-backend communication, and must never be done from a frontend.

Example request:

curl -X POST \
  https://{API_URL}/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic examplebase64encodedcredentials' \
  -H 'Accept: application/json' \
  -d 'grant_type=client_credentials'

Example response:

Content-Type: application/json

{
    "token_type": "bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBJZCI6MzU1LCJjbGllbnRJZCI6InBvcGphbS1hc2VhbiIsInNjb3BlIjoiYXBwIiwiaWF0IjoxNTAxNzcxNjk4LCJleHAiOjE1MDE4NTgwOTgsImlzcyI6InN1cGVyYXdlc29tZSJ9.TsjuG3MWV-e8bHbk7bGNOSQqqsb-zeHxLQG5TuNcbAs",
    "expires_in": 86400
}

Request Headers:

Header Parameter Value Description
Accept application/json Expected format of response
Content-Type application/x-www-form-urlencoded Type of content of body as defined in OAUTH2 standard for this call
Authorization Basic examplebase64encodedcredentials HTTP Basic Auth header with client id and client secret as credentials

Request Body fields:

Body Parameter Required Meaning
grant_type yes Type of auth flow. In this case the value must be client_credentials
scope no Requested scope for the token. If omited app scope is received by default

Response Body fields:

Body Parameter Required Meaning
token_type yes Type of the token. In this call it will always be bearer
access_token yes The access token to be used in the API
expires_in yes Time until expiration of the token in seconds

As shown in the example, and in order to follow OAuth2 specification, the body in this call is sent with form urlencoded format, as opposed to the API, where JSON is always used. The response is however in JSON as also defined in the standard.

The Authorization header in this case corresponds to an HTTP Basic authentication where the username is the client id and the password is the client secret that were obtained when registering the app in KWS (see Getting started section for hints where to get the app credentials and see https://tools.ietf.org/html/rfc2617 for more info about HTTP basic authentication standard).

Authorization code flow

This flow is used when a user wants to sign in the web app. The user has to be redirected to the single sign on website, where they will provide their credentials in order to sign in and then, they will be redirected back to the application. The process can be summed up with the following steps:

  1. The web application detects that the user is not logged in and displays a log in button that links to the single sign on.
  2. The user enters their credentials in the single sign on website.
  3. KWS redirects the user to a callback url in the original application providing an authorization code.
  4. The backend of the application makes a call to KWS to exchange that authorization code for a token with user scope and redirects the user to the website, where in this case the user is authenticated and the generated token can be used to make the necessary API calls.
  5. The app website can optionally store the token by any of the available means (like local storage) so that the session is kept for the next time the user comes back to the app.

Redirecting the user to the single sign-on In order to redirect the user to the single sign-on, apart from the url link itself some parameters have to be sent as in the following URL:

https://{SSO_URL}/en/login?clientId=yourClientId&redirectUri=https://mysite.com/oauthCallback&state=8J%2BOiWV4YW1wbGXwn46JCg%3D%3D

Where {SSO_URL} must be replaced with the corresponding single sign-on website domain that is provided by KWS. The different query parameters of this url are explained in the next table

Single sign-on URL query parameters:

Query Parameter Required Meaning
clientId yes The client ID of the application (can be seen in KWS control panel)
redirectUri yes The callback uri that the user will be redirected to with the authorisation code
state no A value that will be passed back later to the redirected uri

Note

The redirection URI must be added in the app Integration settings in KWS control panel, or it will be rejected!

After the user signs in, they will be redirected to the redirectUri as explained in the next step.

Getting the authorization code and exchanging it for a token

The user has signed in and has been redirected to the callback url, that looks like this:

https://mysite.com/oauthCallback?state=optionalValue&code=authorizationCodeExampleValue

OAuth callback query parameters:

Query Parameter Required Meaning
state no The value that was optionally previously passed to the single sign-on url
code yes A code that will be used by the application Backend in order to exchange it for an access token

Exchanging authorization code for access token

Important

This part of the process must be done in the backend. After that, the obtained access token can be passed to the frontend.

The final step in this flow is to exchange the authorization code for an access token from the Backend, e.g.:

Example request:

curl -X POST \
  https://{API_URL}/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -d 'grant_type=authorization_code&code={CODE}&redirectUri=https://mysite.com/oauthCallback&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}'

Example response:

Content-Type: application/json

{
    "token_type": "bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBJZCI6MzU1LCJjbGllbnRJZCI6InBvcGphbS1hc2VhbiIsInNjb3BlIjoiYXBwIiwiaWF0IjoxNTAxNzcxNjk4LCJleHAiOjE1MDE4NTgwOTgsImlzcyI6InN1cGVyYXdlc29tZSJ9.TsjuG3MWV-e8bHbk7bGNOSQqqsb-zeHxLQG5TuNcbAs",
    "expires_in": 86400
}

Request Headers:

Header Parameter Value Description
Accept application/json Expected format of response
Content-Type application/x-www-form-urlencoded Type of content of body as defined in OAUTH2 standard for this call

Request Body fields:

Body Parameter Required Meaning
grant_type yes The string authorization_code.
code yes This is the value that was passed to the auth callback as the code query parameter.
redirectUri yes The oauth callback redirection uri (it must match the same that was used in previous steps).
client_id yes The OAuth client ID of the application that the user logged into.
client_secret yes The OAuth client secret of the application that the user logged into.

Response Body fields:

Body Parameter Required Meaning
token_type yes Type of the token. In this call it will always be bearer
access_token yes The access token to be used in the API
expires_in yes Time until expiration of the token in seconds

At this point, the OAuth authentication flow would be finished and the access token could be used in both backend and frontend.

Implicit flow

This flow is very similar to the Authentication Code flow, and it can be used when the application does not have a backend or also optionally to simplify the flow in certain cases if necessary, like eventually in native mobile applications. The process can be summed up with the following steps:

  1. The web application detects that the user is not logged in and displays a log in button that links to the single sign on.
  2. The user enters their credentials in the single sign on website.
  3. KWS redirects the user to a callback url in the original application providing an access token with user scope.
  4. The app can now use the token given in the callback url to authenticate the user in the API.

Note

The default and recommended flow for user authentication is the Authorization Code. If the app has to use the Implicit flow instead, this has to be activated in the Integration section of the KWS control panel. Please not that implicit flow is considered less secure than the above authorization code flow, and is not recommended for mobile apps.

Redirecting the user to the single sign-on In order to redirect the user to the single sign-on, apart from the url link itself some parameters have to be sent like in the following URL:

https://{SSO_URL}/en/login?clientId=yourClientId&redirectUri=https://mysite.com/oauthCallback&state=8J%2BOiWV4YW1wbGXwn46JCg%3D%3D

Where {SSO_URL} must be replaced with the corresponding single sign-on website domain that is provided by KWS. The different query parameters of this url are explained in the next table

Single sign-on URL query parameters:

Query Parameter Required Meaning
clientId yes The clientId of the application (can be seen in KWS control panel)
redirectUri yes The callback uri that the user will be redirected to with the authorisation code
state no A value that will be passed back later to the redirected uri

Note

The redirection uri must be added in the app Integration settings in KWS control panel so that it can be accepted

After the user signs in, they will be redirected to the redirectUri as explained in the next step

Getting the token

The user has signed in and has been redirected to the callback url, that looks like this:

https://mysite.com/oauthCallback?state=optionalValue#token=exampleTokenValue

Note

The token is passed to the redirection URI as an anchor in this case, so that it is only available in the frontend.

OAuth callback URL params:

Body Parameter Required Meaning
state no The value that was optionally previously passed to the single sign-on url
token yes The access token to be used in the API. It is passed as an anchor an not as query parameter

From this point the frontend can start using the token to make API calls.

GET /v2/apps/:appId/random-display-name

Generate random display name

This endpoint returns a randomly generated display name based on the nouns and adjectives set for the app’s display names. This display name will have been checked for availability against other user’s display names in the same app. If there are no words set for the current language option, it will fall back to English and attempt to return an English display name.

Note

No authentication required for this endpoint

  • API call
GET /v2/apps/:appId/random-display-name
  • Usage example
curl -X GET 'https://kwsapi.staging.superawesome.tv/v2/apps/random-display-name'
  • Response:
Field Type Description
  string A randomly generated display name that can be displayed to the user and used for the account creation and/or app activation.
  • Response example
"AwesomeNinja8312"

PUT /v1/apps/:appId/random-names

Update display name generator strings

This endpoint allows you to update the list of words for random display name generation. This is a relatively complex endpoint and the data can be set via the UI your KWS Control instead, which is the suggested way of doing this. However, if you wish to do it programatically you may use this endpoint.

Note

Required token type: app

  • API call
PUT /v1/apps/:appId/random-names
  • Parameters:
Parameter Type Description
<locale> Object There needs to be a key with the ISO 639-1 code for each language that has words set. Only ‘en’ needs to exist if you only need English display names.
<locale>.nouns Array List of noun objects for the specified language
<locale>.nouns[].value string The noun itself.
<locale>.nouns[].gender m | f (optional) Set this if the noun has a gender. Does not apply to English but in many languages the gender of the adjective must match the gender of the noun.
<locale>.adjectives Object Array of adjective objects to be matched to the supplied nouns.
<locale>.adjectives.f Array List of feminine adjectives, to be matched with feminine nouns if the language has gendered nouns
<locale>.adjectives.f[].value string The adjective
<locale>.adjectives.f[].beforeNoun string (optional) Whether or not the adjective goes before the noun. Eg. in English, adjectives tend to go before nouns (‘red balloon’), but in Spanish the reverse is true (‘globo rojo’).
<locale>.adjectives.m Array List of masculine adjectives, to be matched with masculine nouns if the language has gendered nouns
<locale>.adjectives.m[].value string The adjective
<locale>.adjectives.m[].beforeNoun string (optional) Whether or not the adjective goes before the noun.
<locale>.adjectives.n Array List of neutral adjectives, to be matched with neutral nouns if the language does not have gendered nouns
<locale>.adjectives.n[].value string The adjective
<locale>.adjectives.n[].beforeNoun string (optional) Whether or not the adjective goes before the noun.
  • Usage example
curl -X PUT 'https://<API_URL>/v1/apps/{appId}/random-names' -H 'Content-Type: application/json' \ -d '{ "en": { "nouns": [ { "value": "Dragon" }, { "value": "Monster" } ], "adjectives": { "n": [ { "value": "Unbeatable", "beforeNoun": true }, { "value": "Evil", "beforeNoun": true } ] } }, "es": { "nouns": [ { "value": "Dragón", "gender": "m" }, { "value": "Bestia", "gender": "f" } ], "adjectives": { "f": { "value": "Malvada", "beforeNoun": false }, "m": { "value": "Malvado", "beforeNoun": false } } } }'

GET /v2/apps/:appId/users/:userId

Get User’s Application Profile

Retrieves the user profile and any related data for the application the user is currently signed into. The app ID in the URL must match the app ID in the access token - that is to say, if a user has authenticated for an application, this endpoint cannot be used to retrieve the profile of the user in another application.

Note

Required token type: user

  • API call
GET /v2/apps/:appId/users/:userId
  • Usage example
curl -X GET 'https://<API_URL>/v2/apps/4214145/users/12837372' -H 'Authorization: Bearer <ACCESS_TOKEN>'
  • Response:
Field Type Description
id number ID of the user.
displayName string Display name of the user within the application.
dateOfBirth string YYYY-MM-DD User’s date of birth, if set
language string ISO 639-1 code of the language of the user.
permissions object An object with a key for each permission, and the value being either true (granted), false (explicitly rejected) or null (neither granted nor rejected yet, implies permission is not granted).
firstName string First name. Will always be null if the user is a child and no permission has granted access to this field.
lastName string Last name. Will always be null if the user is a child and no permission has granted access to this field.
email string Email address. Will always be null if the user is a child and no permission has granted access to this field.
streetAddress string Strees address (part of address. Will always be null if the user is a child and no permission has granted access to this field.
postCode string Postcode/zip code (part of address). Will always be null if the user is a child and no permission has granted access to this field.
city string City (part of address). Will always be null if the user is a child and no permission has granted access to this field.
country string Country (part of address). Will always be null if the user is a child and no permission has granted access to this field.
activationCreatedAt timestamp The date & time the user activated this app.
createdAt timestamp The date & time the user’s account was created.
consentAgeForCountry number The age threshold for requiring parental consent in the country of the user.
isMinor boolean Whether or not the user is considered a child based on the age threshold in the country of the user.
parentState object Object with data on the state of the parent’s account in the Parent Portal
parentState.verified boolean True if the parent has accepted that the user is indeed their child.
parentState.expired boolean True if the email sent to the parent inviting them to the Parent Portal has expired.
parentState.rejected boolean True if the parent denied that the user is their child via the Parent Portal.
parentState.idVerified boolean True if the parent has verified their identity - this action is a requirement for granting some permissions.
parentState.deleted boolean True if the parent’s on the Parent Portal has been deleted.
username string (deprecated) Also returns the display name of the user, NOT the username the user signs in with. This field is now deprecated and will eventually be removed.
  • Response example
{
        "id": 12837372,
        "firstName": null,
        "lastName": null,
        "email": null,
        "dateOfBirth": "2010-01-01",
        "streetAddress": null,
        "city": null,
        "postalCode": null,
        "country": null,
        "displayName": "displayName1234",
        "permissions": {
                "sendNewsletter": true,
                "friendsList": false,
                "enterCompetitions": null
        },
        "activationCreatedAt": "2019-04-18T16:06:40.641Z",
        "createdAt": "2019-04-18T16:06:40.086Z",
        "consentAgeForCountry": 13,
        "isMinor": true,
        "parentState": {
                "verified": true,
                "expired": false,
                "rejected": false,
                "idVerified": false,
                "deleted": false
        },

GET /v1/apps/config

Get App Config by clientId

This endpoint returns the configuration of an app based on the clientId passed as a query parameter.

Note

No authentication required for this endpoint

  • API call
GET /v1/apps/config
  • Parameters:
Parameter Type Description
oauthClientId string client ID of the application.
  • Usage example
curl -X GET 'https://<API_URL>/v1/apps/config?oauthClientId=my-first-app'
  • Response:
Field Type Description
id number ID of the app.
name string App display name, usually used to identify the application to users.
oauthClientId string Client ID; this will be the same as the client ID passed as a query param.
oauthCallbackUrls array Array of approved values to accept as redirectUri when authenticating with OAuth. Only values in this array will be accepted when authenticating the user, and if implementinng your own OAuth client, you should not redirect to any other URL with the token of the authenticated user.
parentEmailRequired boolean If this is true, the app requires collection of a parent’s email address, regardless of the age of the user. This is to say, all users will be treated as if they are children. When false, only users below a certain age will be required to set a parent’s email address.
areAnonAccountsEnabled boolean Whether or not anonymous accounts are enabled. If so, users can sign up without providing a date of birth.
languages array List of supported languages.
  • Response example
{
        "app": {
                "id": 12831,
                "name": "My First App",
                "oauthClientId": "my-first-app",
                "oauthCallbackUrls": ["https://my-app-url.com/oauth-callback"],
                "parentEmailRequired": true,
                "areAnonAccountsEnabled": false
        },
        "languages": ["de", "en", "es"]
}

GET /v1/countries/child-age

Get age gate info

Returns information on the age at which a user is considered a child in the country the request is sent from (which we determine by looking up the request IP address in our geolocation database). If provided an age, it will return whether the user is considered a child or not in the country. This endpoint is useful for building a dynamic age gate that takes into account age limits across countries.

Note

No authentication required for this endpoint

  • API call
GET /v1/countries/child-age
  • Parameters:
Parameter Type Description
dob string (optional) Date of bith of the user in YYYY-MM-DD format. If supplied, will return the age & whether or not this age is considered a child.
country string (optional) Country of the user. If provided, will override the detected country and use this one instead. This option is useful if the request is sent from a server rather than the user, and the user’s country cannot be detected from the IP address of the request.
  • Usage example
curl -X GET 'https://<API_URL>/v1/countries/child-age?dob=2010-10-10'
  • Response:
Field Type Description
country string The detected country from the IP address, or the country overridden via the query params if this was set.
consentAgeForCountry number The age threshold for the country.
age number (optional) The current age of the user, if ‘dob’ was provided in the request.
isMinor boolean (optional) Flag indicating whether the user is under age, based on the age and age threshold for the country. Only sent if ‘dob’ was provided in the request.
  • Response example
{
        "country": "US",
        "consentAgeForCountry": 13,
        "age": 8,
        "isMinor": true
}

POST /v2/users

Create user account

This endpoint creates a new user account on KWS. Once the account has been created, the user can sign in and activate their account in any app using the app activation endpoint. Creating the account does not trigger any emails to be set to parents or allow any permissions to be requested; this depends on an app activation which must be done after the account has been created.

In most cases, the username is required and the email address cannot be set, as the email is considered personally identifiable information. However, for adult users (over the age threshold, which depends on the signup country), the email address can be sent instead of the username.

This endpoint is intended to be sent from the SSO application, directly from the client machine, not server-side. This is important for determining the age threshold for a user to be considered a child or adult, and for the proper functioning of the rate limiting functionality which prevents mass-creation of user accounts.

Note

No authentication required for this endpoint

  • API call
POST /v2/users

Warning

This public endpoint is rate limited, in order to prevent mass-creation of user accounts from a single IP address.

  • Parameters:
Parameter Type Description
username string Login username. Required if user is below the threshold age for parental consent. Must be at least 5 characters long, must start with a letter and can contain only alphanumeric characters, dashes and underscores.
password string Login password. Must be at least 5 characters long.
dateOfBirth string Date of birth of the user, in YYYY-MM-DD format. By default this field is required, but this can be configured to be optional via the Control Panel.
parentEmail string Email address of the parent. Required for users below the threshold age for parental consent, or for all users if configured to be so via the Control Panel.
email string (optional) Email address of the user. May only be set if the user is a adult according to the threshold age, forbidden otherwise.
country string (optional) Country of the user. If not provided, the country will be detected from the IP address of the request. In most cases this default behaviour is desired, as it will properly set the signup country of the user.
  • Usage example
curl -X POST 'https://<API_URL>/v2/users' -H 'Content-Type: application/json' -d '{ "username": "myusername", "password": "password123", "dateOfBirth": "2010-10-10", "parentEmail": "parent_example@superawesome.com" }'
  • Response:
Field Type Description
id number ID of the newly created user.
  • Response example
{
        "id": 374382
}

PUT /v1/users/:userId

Update User Profile

Use this endpoint to update the user’s profile data. In order to set most fields, child users must first have been granted a permission for the current app that enables access to this field. For example, if no permission giving access to the ‘email’ field has been granted for this application, you will not be able to retrieve or set the ‘email’ field. If the user does not have the required permission(s) to set the fields passed into this endpoint, the request will fail with a 403 error code.

Note

Required token type: user

  • API call
PUT /v1/users/:userId
  • Parameters:
Parameter Type Description
firstName string (optional) This field will only be available if the corresponding permission is allowed.
lastName string (optional) This field will only be available if the corresponding permission is allowed.
email string (optional) This field will only be available if the corresponding permission is allowed.
dateOfBirth string (optional) If the date of birth has not previously been set, it can be set here.
parentEmail string (optional) If the parent’s email address has not previously been set, it can be set here.
address object (optional) This field will only be available if the corresponding permission is allowed. It must contain the following fields:
address.street string  
address.postCode string  
address.city string  
address.countryCode string  
language string (optional) ISO 639-1 code of the language of the user. Used to set the default language of email correspondance.
  • Usage example
curl -X PUT 'https://<API_URL>/v1/users/387372081' -H 'Authorization: Bearer <ACCESS_TOKEN> -H 'Content-Type: application/json' -d '{ "firstName":"John", "lastName":"Doe", "email":"j.doe@unknown.com", "language":"en", "address":{ "street":"Example Street", "postCode":"11111", "city":"Example City", "country":"gb" } }'

POST /v1/users/:userId/apps

Activate application

Used for activating a user in the context of an application. A user cannot log in to or interact with an application until they’ve been activated within this application.

When the activation happens, if the child has a parent’s email address set, an email will be sent notifying the parent that the child has started using the application. If the permissions field is set, the parent will also receive requests for these permissions to be granted in the same email, with a link to the Parent Portal allowing them to manage the permissions.

Once activation is complete, the user can sign in to the application to get a user-scoped token for the app, and does not need to activate for the same app again.

Note

Required token type: sso, user

  • API call
POST /v1/users/:userId/apps
  • Parameters:
Parameter Type Description
appName string Client ID of the application, e.g. ‘my-first-app’
displayName string | null (optional) Display name of the user within the application; this is unique across users and across applications. Note that this is different to the username set during accout creation; the account username is used to sign in (and does not get exposed), whereas the display name is what could be displayed to other users within the application. If you don’t require a display name, you can pass null for this field.
permissions string[] (optional) Permissions to request, if desired, in the form of an array of permission identifiers as set when the permissions were created in the Control Panel. Notification of these requests will be sent to the parennt in the activation notification email. Setting this parameter is equivalent to using the ‘Request Permissions” endpoint, but combines the permission request with the activation email and allows the requests to be combined into one.
dateOfBirth string (optional) Date of birth of the child. This will be required if not already set whe creating the account and the application requires a date of birth to be set.
parentEmail string (optional) Parent’s email address. As above, only required if not set when creating the account and the application has a parent email requirement.
  • Usage example
curl -X POST 'https://<API_URL>/v1/users/208914206/apps' -H 'Authorization: Bearer <ACCESS_TOKEN>' -H 'Content-Type: application/json' -d '{"username":"displayName123","appName":"very-excellent-games","permissions":["newsletter"]}'

POST /v1/users/:userId/delete-account

Delete account

Allow a user to delete their account. They must provide the current password for their account as a security measure. Note that if the user has a parentEmail set, an email will be sent to the parent informing them that the account has been deleted.

Note

Required token type: sso

  • API call
POST /v1/users/:userId/delete-account
  • Parameters:
Parameter Type Description
password string the user’s password
  • Usage example
curl -X POST 'https://<API_URL>/v1/users/{userId}/delete-account' -H 'Authorization: Bearer <ACCESS_TOKEN>' -H 'Content-Type: application/json' -d '{"password":"Password123!"}'

POST /v1/users/:userId/request-permissions

Request Permission(s)

This function triggers a permission request to the parent of the user. A permission must first be set up and configured for your application, then any user authenticated in the application can request said permission. When a permission is requested, an email gets sent to the parent informing them of the request and of how to grant access to or revoke the permission.

If sending a request for an opt-out permission, the permission is automatically granted and the parent informed of this, being given the option to revoke the permission. For opt-in permissions, the permission status does not change until the parent explicitly grants it.

This endpoint is intended for use when a user wants to access a specific functionality that they haven’t previously been granted access to. If you know when the user signs up that you want to request certain permissions straight away, you can send the permissions array in the “Activate application” endpoint, in order to request the permissions as part of the app activation email. This avoids having to make two requests and send multiple emails to the parent.

Note

Required token type: user

  • API call
POST /v1/users/:userId/request-permissions
  • Parameters:
Parameter Type Description
permissions string[] Permissions to request, in the form of an array of permission identifiers as set when the permissions were created in the Control Panel.
parentEmail string (optional) If the parent’s email address is not already set for the user, you can set it by passing it here. The user must have this field set in order to request permissions.
dateOfBirth YYYY-MM-DD (optional) Same as the above field. If DoB is not already set, it can be set here.
  • Usage example
curl -X POST 'https://<API_URL>/v1/users/387372081/request-permissions' -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "permissions": ["location"] }'

GET /v1/users/check-username

Check username

Checks that this username is not already taken and that it passes moderation, which checks for an evolving set of criteria such as naughty words and potentially personally identifiable information. Will return true if both of these checks pass, or false if either check fails.

Note

No authentication required for this endpoint

  • API call
GET /v1/users/check-username
  • Parameters:
Parameter Type Description
username string Username to check.
  • Usage example
curl -X GET 'https://<API_URL>/v1/users/check-username?username=myusername123'
  • Response:
Field Type Description
username string The username that was provided.
available boolean Whether or not the username is valid.
  • Response example
{
        "username": "myusername123",
        "available": true,
}

POST /v1/users/forgot-password

Forgot Password

This endpoint allows you to initiate the forgot password flow for a user, triggering an email to be sent to either the child’s email address (if set) or their parent’s email address. The email contains a link which will take the user to a page where they can reset their password. If necessary (e.g. for a custom-build SSO app), this link can be altered in the control panel.

Note

No authentication required for this endpoint

  • API call
POST /v1/users/forgot-password

Warning

This endpoint will return successfully even if the user account was not found. This is a security feature, preventing enumeration of existing usernames by not allowing random usernames to be checked to see whether they have been taken.

  • Parameters:
Parameter Type Description
username string The username to identify
appName string (optional) the client ID of the app this request was made from, if applicable (used for branding the email)
  • Usage example
curl -X POST 'https://<API_URL>/v1/users/forgot-password' -H 'Content-Type: application/json' -d '{"username":"connortest1","appName":"very-excellent-games"}'

POST /v1/users/reset-password

Reset password

This endpoint allows you to use a token to reset a user’s password. The reset password token is generated by KWS and sent to the user (or their parent) via email when the forgot password flow is triggered using the ‘forgot password’ endpoint. After the password is reset, a confirmation email will be sent to the user (or their parent, depending on which email address is set in the account).

Note

No authentication required for this endpoint

  • API call
POST /v1/users/reset-password

Note

This endpoint is only necessary if you are implementing your own ‘forgot password’ flow. By default this is handled by our SSO app, so usage of this endpoint is not necessary.

  • Parameters:
Parameter Type Description
token string The token that was sent to the user in the ‘forgot password’ email.
newPassword string The new password, as chosen by the user.
appName string (optional) The client ID of the app this request was made from, if applicable (only used for branding the email in some cases; in general this endpoint is app-agnostic).
  • Usage example
curl -X POST 'https://<API_URL>/v1/users/reset-password' -H 'Content-Type: application/json' -d '{"newPassword":"mynewpassword","token":"aadc3810-7d77-11e9-a99e-5b46bd2eb1b5","appName":"my-first-app"}'