Custom Auth Screens

KWS' API allows you to build your own custom login screens if you so choose.

Below is an example showing how you can achieve this. Before beginning this process, ensure that you’ve explored best practices to help you find the best authentication flow for your use case. Also consult with your implementation manager for feedback.

Note: we do provide pre-built views which you can utilise to speed up your development cycle. Find out more here.

Sign Up

1) Check if the user is below age of digital consent

After the user provides their date of birth within an age gate (like the one pictured), send a request with that date of birth to the childAge endpoint:

GET /v1/countries/childAge

The response will contain an isMinor boolean that indicates if the user is under the age of digital consent.

2) Create an account

There are multiple discrete steps that need to be performed in order to create an account. These are listed below:

  1. Create an account
  2. Get an OAuth authentication token
  3. Generate a random display name (optional)
  4. Activate the app for this user
  5. Authenticate the user

Creating an account requires capturing the username, password and the parent email. Use the account creation endpoint:

POST: /v2/users

Request body:

Ensure the following data is contained in your request:

Username: String, min 3 characters. Required
password: String; min 5 characters. Required
originAppId: Integer; app ID of the app to brand emails etc with. Required
dateOfBirth: String; YYYY-MM-DD. Required if anonymous accounts disabled  
parentEmail: String; email address. Required if DoB is below age of digital consent

3) Get an authentication token

When authenticating, you first have to make a call to check whether the user is activated, and only activate the user if required. This is because your KWS app may contain various apps and users may be signed up to each of these (but may not be activated in everyone).

Therefore, when creating a user, you must also create the activation before you can authenticate the user within that app.

Get an authentication token by:

POST: /oauth/token
Header: Authorization: Basic base64(‘<appID>:<apiKey>’)

This is the OAuth token endpoint; call it to get a user token with the ‘sso’ scope in order to call the /oauth/authorise endpoint.

The content-type of the request must be x-www-form-urlencoded.

Form data:

You will need to pass through the following data:

grant_type: ‘password’
username: String
password: String

4) Generate random display name (if required)

Random display names can be generated using the randomDisplayName endpoint.

GET /v2/apps/{appId}/randomDisplayName

This endpoint returns a randomly generated display name based on the nouns and adjectives set for the app’s display names in the KWS Control Panel. This display name at the time of the response will not be in use by any other user across the instance of the API.

If there are no nouns and adjectives set for the current language option, it will fall back to English and attempt to return an English display name.

5) Activate the user

Once the user is created, the user will need to be activated on the app using the endpoint below before they can be issued a token for the app.

Activating an account requires the display name to be set (if it is being used).

POST: /v1/users/:userId/apps
Header: Authorization: Bearer <TOKEN>

Request body:

appName: clientId of the app. Required.
username: Display name for the user for this app; has to be different across apps. Set to null for no display name.

On success, the user is activated in the app.

6) Authenticate the user

POST: /oauth/authorise
Header: Authorization: Bearer <TOKEN>

Form data:

response_type: ‘code’
client_id: clientId of the app
redirect_uri: Must be a valid URL as set via the Control Panel

OAuth endpoint; if it returns 403, user is not activated in app so you need to activate. Otherwise returns an auth code that can be exchanged for a token for the signed in user as per OAuth spec.


User login

This is useful if:

  1. The user gets logged out and needs to login again
  2. You have multiple apps using the same login and the user is logging in to the second app

Authentication follows the OAuth framework, with the added complexity of having different apps and users who may not have activated on the app they’re trying to sign in to. Because of this, in most cases when authenticating, you first have to make an extra call to check whether the user is activated, and to activate the user if required.

  1. Get token with SSO scope by POSTing to /oauth/token
  2. Try to authorise: POST: /oauth/authorise using token from above.
    1. If response is 403, activation is required:
      1. Send a POST to /v1/users/:userId/apps
      2. Authenticate user*
    2. If response is successful:
      1. Use the code returned from this endpoint to get an access token using OAuth authorization code grant, or authenticate the user using Password grant*.
    3. Any other response means authentication failed (user not found etc)

* If you know the user has already activated the app they’re trying to access, you can simply POST to /oauth/token using the app’s client ID & API key to form the Basic authorization header (ie. “Authorization: Basic base64(‘<appID>:<apiKey>’)”, to retrieve a token directly using the OAuth Password Grant.


Refreshing tokens

You can use refresh tokens as per the OAuth spec, as explained here: https://auth0.com/learn/refresh-tokens/

To do so, POST to /oauth/token as with getting an access token, but instead of passing the user’s credentials, pass in ‘refresh_token’ for grant_type and the refresh token you already have saved from authentication for the refresh_token. The response will contain a new access token and a new refresh token, which should replace the existing one you had stored.

Refresh tokens expire every 14 days by default.

Managing Permissions

Request permissions

We recommend allowing for a zero-data experience for kids so that they can engage with parts of your app/website without parental consent. For the best UX, consider only asking for permissions when absolutely required.

To request specific permissions, use the requestPermissions endpoint.

POST /v1/users/{userId}/requestPermissions

Check permissions status

To check if a specific permission has been granted, use the getUserProfile endpoint. The response has a permissions object that lists the boolean value of the current state of the requested permissions.

To delete a user and/or their data, use the delete App Data endpoint.

POST /v1/apps/{appId}/users/{userId}/appData/deleteByName
dateOfBirth: String; YYYY-MM-DD. Required if anonymous accounts disabled  
parentEmail: String; email address. Required depending on DoB,

Send a request here to create the user. Once created, the user will need to be activated on the app using the /v1/users/:userId/apps endpoint below before they can be issued a token for the app.


Delete account

Call the deleteByName endpoint to delete data related to the user in that specific app.

POST /v1/apps/{appId}/users/{userId}/appData/deleteByName