Docs

Guides

Blog

Tools

Token2 TOTPRadius appliance Web API

Token2 API is a RESTful API for enabling two-factor authentication of users of a website or a web application. To start using Token2 TOTPRadius appliance Web API, you will need to have the TOTPRadius appliance installed and reachable. This API uses keys that can be set on TOTPRadius admin panel.  The web API is implemented for TOTPRadius appliance v0.2.1 and above.

Create a user

http[s]://totpradius_appliance_ip/createuser?api_key=[api_key]&phone=[mobile_phone]&email=[email]&type=[authentication type]&pin=[pin code]&format=[response format]

This API call requires the following arguments to be provided:

  • api - the API key for the website. Can be obtained or set in the admin panel of the appliance
  • phone - the mobile phone number of the user in e.164 format.
  • email - User's email address
  • type - Authentication type to be used. Following values are possible: 0 - mobile application only (default). There is no other options for TOTPRadius appliance Web API . Kept for backward compatibility with Token2 Cloud API.
  • pin - PIN code, not required for TOTPRadius appliance Web API. Kept for backward compatibility with Token2 Cloud API.
  • format - format of the response data. Values: 1- json, 2- xml, 3- simplified plain text (true or false, no details or description), 0- serialized data (default)
Response
This call return the following data upon successful execution:
  • response - result's description (e.g. "user created")
  • userid - user's unique ID. This ID will need to be stored and associated with your local user database. User ID is required to validate/generate/send OTP codes
  • success - returns "true" if the user was successfully created and assigned a unique Token2 ID
  • hash - User's secret key to be added to the Token2 Mobile Application or any other TOTP Mobile application
  • hashqr - QR Code image URL of user's secret key to be scanned using Token2 Mobile Application

Validate an OTP

API call to validate an OTP password provided by user. 
http[s]://totpradius_appliance_ip/validate?api_key=[api key]&token=[OTP]&userid=[User's Token2 ID]&format=[response format]

This API call requires the following arguments to be provided:
  • api - the API key for the website.  
  • userid - User's Token2 ID.
  • token - OTP to be verified
  • format - format of the response data. Values: 1- json, 2- xml, 3- simplified plain text (true or false, no details or description), 0- serialized data (default)
Response
This call return the following data upon successful execution:
  • response - result's description in English (e.g. "OTP generated and sent by SMS")
  • userid - User's Token2 ID
  • validation - returns "true" if OTP provided via API is valid, or "false" if not valid. Use this value to check if a user should be authenticated.

List current users

[this API call is available from v0.2.8 ]

http[s]://totpradius_appliance_ip/api.php?api_key=[api key]&action=listusers

This API returns the list of current users in JSON format only, containing the userid, username and the registration timestamp.


Change Local User Password

[this API call is available from v0.3.1]

GET /api.php?action=changelocaluserpassword&user={username}&localpassword={new_password}&api_key={api_key}

Description

Changes the password of an existing local user.

Parameters
  • user (string): The username of the user whose password will be changed.
  • localpassword (string): The new password for the user.
Example Response
  • Success: Success: user password changed
  • Error: Error: password too short (we expect at least 6 chars)

Delete Local User

[this API call is available from v0.3.1]

GET /api.php?action=deletelocaluser&user={username}&api_key={api_key}

Description

Deletes an existing local user.

Parameters
  • user (string): The username of the user to be deleted.
Example Response
  • Success: Success: user deleted
  • Error: Error: user does not exist