Getting started

Getting started with the Identity API

Service page:

Time-base One-Time Passwords: Users can quickly be enrolled with the One-Time Password service and use the Google Authenticator mobile app on their mobile to generate OTPs. The user provides the OTP that was generated on their mobile and the service then verifies this.

TOTP Service: Verify code from user when using Google Authenticator

Enroll user with service: Make REST API call to add user to service. Provide user with enrolment link for them to scan QR code with Google Authenticator.

When user then performs login or transaction, ask them for TOTP code from Google Authenticator. Make a REST API call to the OTP service and provide the TOTP code from the user and the user's OTP service user ID. The service will then verify if the provided code is valid for that user at that time.


API key for Identity API must be obtained from service page

Click Sign Up | Login to Get Service at

Create Domain

Create an authentication domain for users.

curl \
	--header 'x-api-key: [API_KEY]' 

{"domain": "cabcc674-a328-432d-b925-0d5c3e79a183"}

Create user

Create a user within an authentication domain.

return_secret set to true will cause the generated secret to be returned. This should then be given to the user to add into Google Authenticator and enrolment will be assumed to have been completed. When set to false, or omitted, the secret will not be returned and instead an enrolment URL will be returned. The enrolment URL allows users to add the secret themselves to Google Authenticator.

set_secret is used to specify the secret to be used, rather than the service generate a secret.


We recommend the use of anonymised user IDs (user_id) with the service, rather than email addresses or similar that third parties can easily identify individuals with. Examples use email address to clearly illustrate purpose of field.

curl \
	--header 'x-api-key: [API_KEY]' --header 'Content-Type: application/json' \
	--data-raw '{"domain": "cabcc674-a328-432d-b925-0d5c3e79a183", "user_id": "[email protected]", "return_secret": true}'

{"domain": "cabcc674-a328-432d-b925-0d5c3e79a183", "user_id": "[email protected]", "secret": "QIATV7YPGLQKDDIC", "type": "totp", "interval": 30}

Identity Check

Check time-based code provided by user is correct.

curl \
	--header 'x-api-key: [API_KEY]' --header 'Content-Type: application/json' \
	--data-raw '{"user_id": "[email protected]", "code": "704471", "domain": "f5af5a70-e34c-40ad-8e6b-9e2cc883364f"}'

{"verified": true}