1. Home
  2. Kid Account Management
  3. Build a custom authentication UI

Build a custom authentication UI

If you are using KWS’s kid account management service, you typically also use KWS’ out-of-the-box SSO view to handle your sign-up/sign-in flow. However, in some cases it may be desirable to build and host your own custom interface to handle user sign-up and sign-in.  This section describes how to build a custom authentication UI that uses the KWS API to handle your flow.

If your app requires functionality that is not described here, contact your Implementation Manager.

What your custom authentication UI needs to do

1. Create a KWS user account.

2. Log the user in to your app. This consists of:

  • authenticating the user
  • activating the user in the app
  • authorising the user

3. Trigger a permission review/request.

4. Enable the user to delete their account.

5. Enable the user to reset their password.

UI guidelines

Follow these UI guidelines to ensure that the interface you build remains compliant while achieving the best UX for your users:

Sign-up view
view (1)
view (2)
Ask for permission
Submit parent email address
Email notification

1. Create a user account

First, your authentication UI needs to be able to create an account for each new user. To create a user account, follow these steps:

1.1 Capture the user’s sign-up details

To register a user (create an account), you need a form that enables the user to enter a username and password. Depending on the configuration of your app, they may also need to enter their date of birth and (if they are below the age of digital consent) a parent’s email address. 

Depending on your app’s configuration, you may wish to present a separate age gate, such as the one shown here, before the authentication UI.

1.2 Check if the user is below age of digital consent

Send a request with the user’s DoB, and optionally their country, to the child-age endpoint. This endpoint returns an isMinor Boolean that indicates if the user is under the age of digital consent. 

1.3 Check that the provided username is unique

Call the check-username endpoint to ensure that the entered username is unique and passes moderation.

1.4 Send the data to the user creation endpoint

Submit the form data to the user creation endpoint, which creates a KWS user account.

1.5 Generate a display name for the new user (optional)

If required, call the random-display-name endpoint to generate a display name for the new user.

This endpoint generates a random name from the nouns and adjectives that you set up in the Control Panel. See Set up display names for details.

2. Log the user in to your app

Now that the user has been registered successfully with an account, your authentication UI needs to log the user in and activate them in the app before an authorisation code can be retrieved and sent back to the app. This functionality is required when:

  • A user gets logged out and needs to log in again.
  • You have multiple apps using the same authentication UI and the user is logging into a ‘new’ app for the first time.

Authentication follows the OAuth framework, with the added complexity of having multiple apps: the user may be activated on one app but not on the app they’re trying to sign in to.

This is a summary of the log-in flow:

Authenticate / get access tokenGet an access token with SSO scope by POSTing to /oauth/token.
Try to authorisePOST to /oauth/authorise using that access token.

– If unsuccessful (response 403), you need to activate on the app by POSTing to /v1/users/:userId/apps.

– If successful, use the code returned from /oauth/authorise to get an access token using OAuth authorization code grant, or authenticate the user using Password grant.

– Any other response means authentication failed (for example, user not found).

The following sections describe authentication, authorisation, activation and refreshing the token in more detail:

2.1 Authenticate the user / Get an access token

To log a user in, first the OAuth Password Grant must be used to get an OAuth authentication token (“access token”) with SSO scope. To do this, POST to the /oauth/token endpoint.

If you know the user is already activated on the app they’re trying to access, you can simply POST to /oauth/token using the app’s client ID and API key to form the Basic authorization header:
Authorization: Basic base64(‘<appID>:<apiKey>’)
This retrieves a token directly using the OAuth Password Grant.

When the user is successfully authenticated, the response returns an access token in the form of a JSON Web Token (JWT) which has the scopes ‘sso’ and ‘user’.


curl -X POST \
  https://{API_URL}/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept-Language: en' \
  -H 'Authorization: Basic c3VwZXJhd2Vzb21lY2x1YjpzdXBlcmF3ZXNvbWVjbHVi' \
  -H 'Accept: application/json, text/plain, */*' \
  -d 'grant_type=password&username=<username>&password=<password>'

Storing the access token

This token should not be exposed outside of the authentication UI. However, you can store it and use it to retrieve an auth code, which can be returned to the application and used to get a token with the correct scope. 

It is recommended that you store the token as a cookie so it can be used later by the user if they return to the app and wish to log in again, or if they wish to manage their account.

2.2 Authorise the user

Now that you have the access token, you can authorise the user, using the /oauth/authorise endpoint.

  • If successful, this endpoint returns an auth code that can be exchanged for a token for the signed-in user, as per the OAuth 2.0 authorisation framework. On getting a successful response, redirect the user to the ‘redirect URI’ passed to this request. 
  • If you get a ‘403’ error response from this request, it means the user is not yet activated in the application. Make a request to the activation endpoint (as described in Activate the user on the app below) and then attempt the login request again.


curl -X POST \   
https://{API_URL}/oauth/authorise \   
-H 'Content-Type: application/x-www-form-urlencoded' \   
-H 'Accept-Language: en' \   
-H 'Accept: application/json, text/plain, */*' \   
-H 'Authorization: Bearer <token>' \   
-d 'response_type=code&client_id=<appClientId>&redirect_uri=<appRedirectUri>'

2.3 Activate the user on the app

If this is the first time the user is logging in to the app, you need to activate the user for that app, by POSTing to the /v1/users/:userId/apps endpoint.

Whether the user has just created an account or is logging in to a new app using an existing account, they must be activated in the app before they can be authorised and provided with a token scoped to the app.

2.4 Refresh the token

A refresh token allows your app to obtain a new access token without prompting the user.

You can refresh an access token, as described in the OAuth spec

To do so, POST to /oauth/token as in Authenticate the user / Get an access token, but instead of passing the user’s credentials, use:

  • grant_type: ‘refresh_token’
  • refresh_token: the refresh token you saved from authentication

The response contains:

  • a new access token
  • a new refresh token which replaces the one you had stored

Refresh tokens expire every 14 days by default.

3. Trigger a permission request/review

Your authentication flow needs to include the capability to monitor the user’s permissions status, and to prompt the parent via email to grant or review their child’s permissions. To implement this, use the following endpoints:

Check a user’s permissions status

To check if a user has been granted a permission, you can use either of the following:

  • the permissions endpoint. This endpoint returns a permissions object that lists each permission and a Boolean value that indicates if the permission has been granted, denied, or is still pending.
  • the get profile endpoint. This endpoint retrieves the user profile which includes a permissions object, as above, that lists each permission and a Boolean value that indicates if the permission has been granted, denied, or is still pending.

Request permissions from parent

To ask the parent to grant specific permissions, use the request-permissions endpoint.

This endpoint is called from your app. When a child performs an action in your app that needs a specific permission, you can call this endpoint to send a request to the child’s parent. The endpoint triggers a permission request email to the child’s parent. The email informs the parent of the request and explains how to grant or revoke the permission. 

The permission must first be set up in the KWS Control Panel.

Ask parent to review their child’s permissions

To ask a parent to review their child’s permissions, use the review-permissions endpoint. This endpoint sends an email to the parent with an authenticated link to the Parent Portal. When the parent clicks on the link, they are automatically logged into the Parent Portal where they can review their child’s permissions.

4. Enable the user to delete their account

To comply with GDPR, your authentication UI must allow a user to delete their account.

To delete the user’s account on their behalf, call the delete-account endpoint, specifying the user’s ID in the URL and their password in the request body.

When calling this endpoint, you must provide an access token which has the sso scope, such as that obtained via the /oauth/token endpoint (see Authenticate the user / Get an access token).

5. Enable the user to reset their password

Your authentication UI must enable users to reset their password. To provide this functionality, you need to implement two pages:

  • A page to collect the user’s username and trigger the ‘forgot password’ email.
  • A page to reset the user’s password and send a confirmation email.

Each page needs to call a KWS endpoint to trigger the required actions, as described next.

For both of the endpoints, the appName parameter (which takes the ID of your application as its value) is optional. If provided, it is used to apply your app-specific branding to the emails that KWS sends.

5.1 Trigger a ‘Forgot password‘ email

First, call the forgot-password endpoint, providing the user’s username and optionally the client ID of your application. This endpoint triggers an email to be sent to the child (or their parent, if no email address is associated with the child’s account), containing a link with a password reset token.

For security reasons, this endpoint always returns 204 No Content, whether or not the specified user exists in KWS.

When the user clicks on the ‘reset password’ link in the email and lands on your ‘reset password’ page, your application must:

  • extract the password_reset_token query parameter from the URL.
  • use this to call the reset-password endpoint, along with the user’s new password and optionally the client ID of your application. This endpoint triggers an email to be sent to the child (or their parent, if no email address is associated with the child’s account), confirming the password change.

You need to ask your Implementation Manager to configure the ‘reset password’ URL to enable these generated emails to link to your authentication UI.

Updated on 22/04/2021

Was this article helpful?

Related Articles