INTRODUCTION

Welcome to the GAuthify Two-Factor Authentication (2FA) API. This quick start guide should provide you all the information you need to integrate GAuthify.

To install

pip install --upgrade https://github.com/jkbrzt/httpie/tarball/master

gem install gauthify

pip install gauthify

Install-Package GAuthifyAPI

Our shell code uses httpie to make HTTP requests. If you prefer curl the syntax is fairly similar: curl -a :<apikey> ...

HTTPie Windows installation tutorial can be found here

AUTHENTICATION

Authenticating to the API can be done in two ways:

1) Via an Http Basic Auth (no username, password=apikey)

Authorization: Basic <b64>

2) Via the URL parameter api_key

https://api.gauthify.com/?api_key=<api_key>

USAGE

Initiate: First get an API key by signing up for an account here

First instantiate a GAuthify object:

require 'gauthify'
auth_instance = GAuthify.new("ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ")

from gauthify import GAuthify
auth_instance = GAuthify("ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ")

using GAauthify_API
var auth_instance = new GAuthifyAPICalls("ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ)

REALM

The realm

JSON schema for a realm:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "required": true
    },
    "meta": {
      "type": ["object", "null"],
      "required": true
    }
  },
  "additionalProperties": false
}

A Realm is the scope of an API key. Realms isolate your resources into logical groups. Examples can be “staging”, “develpment”, “us-east”, etc.

View Your Realm Metadata

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/realm/

auth_instance.get_realm(page=nil)

auth_instance.get_realm(page=None)

auth_instance.GetRealm()

Sample JSON return

{
    "data": {
        "meta": {
            "organization_name": "Corp Name"
        },
        "name": "API-Playground"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>"
}

Update Your Realm Metadata

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ PUT https://api.gauthify.com/v1/realm/ \
      meta='{ "organization_name" : "Corp Name"}'

auth_instance.update_realm(meta=nil)

auth_instance.update_realm(meta=None)

auth_instance.UpdateRealm()

Sample JSON return

{
    "data": {
        "meta": {
            "organization_name": "Corp Name"
        },
        "name": "API-Playground"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>"
}

USERS

The User Object

JSON Schema for a user:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "unique_id": {
      "type": "string",
      "required": true
    },
    "display_name": {
      "type": "string",
      "required": true
    },
    "created_at": {
      "type": "string",
      "required": true
    },
    "groups": {
      "type": ["array", "null"],
      "required": true
    },
    "meta": {
      "type": ["object", "null"],
      "required": true
    },
    "sms_number": {
      "type": ["string","null"],
      "required": true
    },
    "voice_number": {
      "type": ["string","null"],
      "required": true
    },
    "email": {
      "type": ["string","null"],
      "required": true
    }
  },
  "additionalProperties": false
}

A user is one of your 2FA consuming users.

Get All Users

To retrieve all Users:

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/users/?page=1

auth_instance.get_all_users()

auth_instance.get_all_users()

auth_instance.GetAllUsers()

Returns list of Users

Parameters

Parameter	Default	Description
page	1	The page of data to be returned

Create A User

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/users/ \
      unique_id=user_1 \
      [email protected]' \
      sms_number='2134567890' \
      voice_number='+12134567890' \
      display_name='John Doe' \
      groups='["group_1", "group_2"]'

auth_instance.create_user(unique_id="user_1", display_name="John Doe", email="[email protected]", sms_number="2134567890", voice_number="+12134567890", groups='["group_1", "group_2"]', meta=nil)

auth_instance.create_user(unique_id="user_1", display_name="John Doe", email="[email protected]", sms_number="2134567890", voice_number="+12134567890", groups='["group_1", "group_2"]', meta=None)

auth_instance.CreateUser(string uniqueId="user_1", string displayName="John Doe", string email = "[email protected]", string smsNumber = "2134567890", string voiceNumber = "+12134567890", List<string> groups = ["group_1", "group_2"], Dictionary<string, string> meta = null)

Sample JSON return

{
    "data": {
        "created_at": "<datetime>",
        "display_name": "John Doe",
        "email": "[email protected]",
        "groups": [
            "group_1",
            "group_2"
        ],
        "meta": null,
        "sms_number": "+12134567890",
        "unique_id": "user_1",
        "voice_number": "+12134567890",
        "display_name": "John Doe"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>",
    "user_count": 1
}

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Your internal identifier for this user (probably user PK). This is how this user is queried throughout this API
display_name	null	A display name to use in communication templates (if required)
email	null	The user’s 2FA email
sms_number	null	The number to used SMS user (see phone formatting)
voice_number	null	The number to use to call user (see phone formatting)
groups	null	A Json string representing an array of strings e.g ’[“group_1”, “group_2”]’
meta	null	A Json string representing a json object of key/value strings e.g. ’{“zone” : “uk”}’

Get A Specific User

To retrieve a specific user.

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/users/user_1/

auth_instance.get_user(unique_id="user_1")

auth_instance.get_user(unique_id="user_1")

auth_instance.GetUser(string unique_id="user_1")

Sample JSON return

{
    "data": {
        "created_at": "<datetime>",
        "display_name": "John Doe",
        "email": "[email protected]",
        "groups": [
            "group_1",
            "group_2"
        ],
        "meta": null,
        "sms_number": "+12134567890",
        "unique_id": "user_1",
        "voice_number": "+12134567890",
        "display_name": "John Doe"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>",
    "user_count": 1
}

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Your internal identifier for this user (probably user PK). This is how this user is queried throughout this API

Update A User

You can update most fields you created a user with.

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ PUT https://api.gauthify.com/v1/users/user_1/ \
      [email protected]'

auth_instance.update_user(unique_id="user_1", display_name="John Doe", email="[email protected]", sms_number="+12134567890", voice_number="+12134567890", groups='["group_1", "group_2"]', meta=nil)

auth_instance.update_user(unique_id="user_1", display_name="John Doe", email="[email protected]", sms_number="+12134567890", voice_number="+12134567890", groups='["group_1", "group_2"]', meta=None)

auth_instance.UpdateUser(string uniqueId = "user_1", string displayName = "John Doe", string email = "[email protected]", string smsNumber = "+12134567890", string voiceNumber = null, List<string> groups = ["group_1", "group_2"], Dictionary<string, string> meta = null)

Sample JSON return:

{
    "data": {
        "created_at": "<datetime>",
        "display_name": "John Doe",
        "email": "[email protected]",
        "group": "group_1",
        "sms_number": "+12134567890",
        "unique_id": "user_1",
        "voice_number": "+12134567890"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>",
    "user_count": 1
}

Parameters

Parameter	Default	Description
unique_id	null	Your internal identifier for this user (probably user PK). This is how this user is queried throughout this API
display_name	null	A display name to use in communication templates (if required)
email	null	The users 2FA email
sms_number	null	The number to used SMS user (see phone formatting)
voice_number	null	The number to use to call user (see phone formatting)
groups	null	A Json string representing an array of strings e.g ’[“group_1”, “group_2”]’
meta	null	A Json string representing a json object of key/value strings e.g. ’{“zone” : “uk”}’

Delete A User

When deleting a user, the final state of the user is returned for reference with the response.

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Your internal identifier for this user (probably user PK). This is how this user is queried throughout this API

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ DELETE https://api.gauthify.com/v1/users/user_1/

auth_instance.delete_user(unique_id="user_1")

auth_instance.delete_user(unique_id="user_1")

auth_instance.DeleteUser(string uniqueId = "user_1")

Check if User Exists

If a user doesn’t exist, the server returns a 404 error. Clients wrap this into a boolean. A HEAD request can be used if the response body isn’t needed.

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ HEAD https://api.gauthify.com/v1/users/user_1/

auth_instance.get_user(unique_id="user_1")

auth_instance.get_user(unique_id="user_1")

404 returned if user DNE

HTTP/1.1 404 NOT FOUND
Allow: GET, PUT, DELETE, HEAD, OPTIONS
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
X-Frame-Options: SAMEORIGIN

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Your internal identifier for this user (probably user PK). This is how this user is queried throughout this API

TEMPLATES

The Template Object

JSON Schema for a template:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "required": true
    },
    "body": {
      "type": "string",
      "required": true
    },
    "subject": {
      "type": ["string", "null"],
      "required": true
    },
    "lang": {
      "type": "string",
      "required": true
    },
    "created_at": {
      "type": "string",
      "required": true
    }
  },
  "additionalProperties": false
}

Get All Templates

To retrieve all Templates:

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/templates/?page=1

auth_instance.get_all_templates()

auth_instance.get_all_templates()

auth_instance.GetAllTemplates(string page = null)

Returns list of Templates

Parameters

Parameter	Default	Description
page	1	The page of data to be returned

Create A Template

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/templates/ \
      template_id=my_template_1 \
      body='This is the body {{ otp }}' \
      lang='en-US'

auth_instance.create_message_template(template_id="my_template_1", body="This is the body {{ otp }}", lang="en-US", subject=nil)

auth_instance.create_message_template(template_id="my_template_1", body="This is the body {{ otp }}", lang="en-US", subject=None)

auth_instance.CreateTemplate(string templateId = "my_template_1", string body = "This is the body {{ otp }}", string lang = "en-US")

Sample JSON return:

{
    "data": {
        "created_at": "<datetime>",
        "body": "This is the body {{ otp }}",
        "created_at": "2015-11-10T07:34:14.079347Z",
        "lang": "en-US",
        "template_id": "my_template_1"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>"
}

Parameters

Parameter	Default	Description
template_id	REQUIRED	Your internal identifier for this template.
body	null	The content/body of the template which includes template tags. See template tags.
lang	null	The language (mostly used for voice). See lang format.
subject	Optional	The subject to use if this template is emailed

Get A Specific Template

To retrieve a specific template.

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/templates/my_template_1/

auth_instance.get_message_template(template_id="my_template_1")

auth_instance.get_message_template(template_id="my_template_1")

auth_instance.GetTemplate(string templateId = "my_template_1")

Sample JSON return:

{
    "data": {
        "body": "This is the body {{ otp }}",
        "lang": "en-US",
        "template_id": "my_template_1",
        "created_at": "<datetime>"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>"
}

Parameters

Parameter	Default	Description
template_id	REQUIRED	Your internal identifier for this template.

Update A Template

You can also update a template.

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ PUT https://api.gauthify.com/v1/templates/my_template_1/ \
      body='This is a new body {{ otp }}!'

auth_instance.update_message_template(template_id="my_template_1", body="This is a new body {{ otp }}!", lang=nil, subject=nil)

auth_instance.update_message_template(template_id="my_template_1", body="This is a new body {{ otp }}!", lang=None, subject=None)

auth_instance.UpdateTemplate(string templateId = "my_template_1", string body = "This is a new body {{ otp }}!", string lang = null)

Sample JSON return:

{
    "data": {
        "created_at": "<datetime>",
        "body": "This is a new body {{ otp }}!",
        "lang": "en-US",
        "template_id": "my_template_1"
    },
    "request_id": "fe3393e0d01245af8a12a15265404399",
    "server_time": "<datetime>"
}

Parameters

Parameter	Default	Description
body	null	The content/body of the template which includes template tags. See template tags.
lang	null	The language (mostly used for voice). See lang format.
subject	Optional	The subject to use if this template is emailed

Delete A Template

When deleting a template, the final state of the template is returned for reference with the response.

Parameters

Parameter	Default	Description
template_id	REQUIRED	Your internal identifier for this template.

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ DELETE https://api.gauthify.com/v1/templates/my_template_1/

auth_instance.delete_message_template(template_id="my_template_1")

auth_instance.delete_message_template(template_id="my_template_1")

auth_instance.DeleteTemplate(string templateId = "my_template_1")

Check if Template Exists

If a template doesn’t exist, the server returns a 404 error. Clients wrap this into a boolean. A HEAD request can be used if the response body isn’t needed.

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ HEAD https://api.gauthify.com/v1/tempaltes/my_template_1/

404 returned if template DNE:

HTTP/1.1 404 NOT FOUND
Allow: GET, PUT, DELETE, HEAD, OPTIONS
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
X-Frame-Options: SAMEORIGIN

Parameters

Parameter	Default	Description
template_id	REQUIRED	Your internal identifier for this template.

SMS

The SMS Object

JSON Schema for an SMS:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "guid": {
      "type": "string",
      "required": true
    },
    "user_unique_id": {
      "type": "string",
      "required": true
    },
    "otp_id": {
      "type": "string",
      "required": true
    },
    "created_at": {
      "type": "string",
      "required": true
    },
    "to_address": {
      "type": ["string","null"],
      "required": true
    },
    "cost_cents": {
      "type": ["integer","null"],
      "required": true
    },
    "state": {
      "type": ["string","null"],
      "required": true
    }
  },
  "additionalProperties": false
}

SMSes are standard GSM messages with full global support. Important notes regarding SMSes in general:

• Per the GSM spec unicode characters are split into multiple messages of 78 characters
• Warn your users of potential charges they may receive from their telco/etc
• A standard ASCII SMS is 160 characters long. Messages will be split automatically as appropriate, billing is per message.

Numbers are sticky to a user and are geo-routed and load balanced to enhanced user experience. Frequently contacted countries should be reported to support for number pre-allocation (not required).

Sending An SMS

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/sms/ \
      unique_id=user_1 \
      template_override='Testing GAuthify Docs {{ otp }}.' \
      phone_override='+123245'

auth_instance.send_sms_token(unique_id="user_1", phone_override="+123245", template_override="Testing GAuthify Docs {{ otp }}.", expire_override=nil,
                                                    template_id=nil, meta=nil)

auth_instance.send_sms_token(unique_id="user_1", phone_override="+123245", template_override="Testing GAuthify Docs {{ otp }}.", expire_override=None,
                                                    template_id=None, meta=None)

auth_instance.SendSMS(string uniqueId = "user_1", string phoneOverride = "+123245", string expireOverride = null, string templateOverride = "Testing GAuthify Docs {{ otp }}.", string templateId = null)

Sample JSON return:

{
    "data": {
        "guid" : "07e61c512d804bfda6a953ed3cced5ab",
        "cost_cents": null,
        "created_at": "<datetime>",
        "otp_id": "0674c34ec177444a901c0fc0a46f0830",
        "state": "SENT",
        "to_address": "+13015121902",
        "user_group": "group_1",
        "user_unique_id": "user_1"
    },
    "request_id": "c9bcf26d879f43828780f68b0b51f12b",
    "server_time": "<datetime>"
}

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Unique id of user to send message to
phone_override	Required if sms_number not set	The number to sms (see phone formatting)
template_override	Optional	If you want to override the template. (see template tags)
template_id	Optional	Optional existing Template template_id
meta	null	A Json string representing a json object of key/value strings e.g. ’{“zone” : “uk”}’

Checking SMS Log

To retrieve all SMSes:

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/sms/?page=1

auth_instance.get_all_sms()

auth_instance.get_all_sms()

auth_instance.GetAllSMS(string page = null)

Returns list of SMS objects

VOICE (CALLING)

The Voice Object

JSON Schema for a Voice Object:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "guid": {
      "type": "string",
      "required": true
    },
    "user_unique_id": {
      "type": "string",
      "required": true
    },
    "otp_id": {
      "type": "string",
      "required": true
    },
    "created_at": {
      "type": "string",
      "required": true
    },
    "to_address": {
      "type": ["string","null"],
      "required": true
    },
    "cost_cents": {
      "type": ["integer","null"],
      "required": true
    },
    "state": {
      "type": ["string","null"],
      "required": true
    }
  },
  "additionalProperties": false
}

Voice calls are made to a user and the one time password is read aloud.

Making A Call

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/voice/ \
      unique_id=user_1 \
      phone_override='+123245'

auth_instance.send_voice_token(unique_id="user_1", phone_override="+123245", template_override=nil, expire_override=nil,
                                                        template_id=nil, meta=nil)

auth_instance.send_voice_token(unique_id="user_1", phone_override="+123245", template_override=None, expire_override=None,
                                                        template_id=None, meta=None)

auth_instance.SendVoice(string uniqueId = "user_1", string phoneOverride = "+123245", string expireOverride = null, string templateOverride = null, string templateId = null)

Sample JSON return:

{
    "data": {
        "cost_cents": null,
        "created_at": "<timestamp>",
        "otp_id": "e1843f38295b465391c345dd67c4c9e1",
        "state": "SENT",
        "to_address": "+13015121902",
        "user_group": "group_1",
        "user_unique_id": "user_1"
    },
    "request_id": "ed40adf67def400f833e220146a14948",
    "server_time": "<timestamp>"
}

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Unique id of user to send message to
phone_override	Required if voice_number not set	The number to call (see phone formatting)
template_override	Optional	If you want to override the template. (see template tags)
template_id	Optional	Optional existing Template template_id
meta	null	A Json string representing a json object of key/value strings e.g. ’{“zone” : “uk”}’

Checking Voice/Call Log

To retrieve all voice calls

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/voice/?page=1

auth_instsance.get_all_voice_calls()

auth_instsance.get_all_voice_calls()

auth_instance.GetAllVoice(string page = null)

Returns list of Voice objects

E-MAIL

The Email Object

JSON Schema for an Email Object:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "guid": {
      "type": "string",
      "required": true
    },
    "user_unique_id": {
      "type": "string",
      "required": true
    },
    "otp_id": {
      "type": "string",
      "required": true
    },
    "created_at": {
      "type": "string",
      "required": true
    },
    "to_address": {
      "type": [
        "string",
        "null"
      ],
      "required": true
    }
  },
  "additionalProperties": false
}

You can also email a user their 2FA code.

Sending An Email

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/email/ \
      unique_id=user_1 \
      [email protected]' \
      template_override='Test email from docs! Your otp: {{ otp }}.' \
      subject_override='my_subject'

auth_instance.send_email_token(unique_id="user_1", email_override="[email protected]", subject_override="my_subject", template_override="Test email from docs! Your otp: {{ otp }}.",
                                                        expire_override=nil, template_id=nil, is_html=nil, meta=nil)

auth_instance.send_email_token(unique_id="user_1", email_override="[email protected]", subject_override="my_subject", template_override="Test email from docs! Your otp: {{ otp }}.",
                                                        expire_override=None, template_id=None, is_html=None, meta=None)

auth_instance.SendEmail(string uniqueId="user_1", string emailOverride = "[email protected]", string subjectOverride = "my_subject", string expireOverride = null, string templateOverride = "Test email from docs! Your otp: {{ otp }}.", string templateId = null)

Sample JSON return:

{
    "data": {
        "created_at": "<timestamp>",
        "otp_id": "b5efeb9b6c1d4a308bb96d6342353d63",
        "to_address": "[email protected]",
        "user_group": "group_1",
        "user_unique_id": "user_1"
    },
    "request_id": "ed40adf67def400f833e220146a14948",
    "server_time": "<timestamp>"
}

The email will be delivered to the user immediately.

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Unique id of user to send message to
email_override	Required if email not set	The email to send to.
subject_override	Optional	If you want to override the subject.
expire_override	Optional	Seconds after which the OTP will expire
template_override	Optional	If you want to override the template. (see template tags)
template_id	Optional	Optional existing Template template_id
meta	null	A Json string representing a json object of key/value strings e.g. ’{“zone” : “uk”}’
is_html	null	“1” or “TRUE” if the email is to be sent as an html email

Checking Email Log

To retrieve all emails

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/email/?page=1

Returns list of Email objects

CHECK ONE TIME PASSWORD (OTP)

The Check Object

JSON schema for a check:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "authenticated": {
      "type": "boolean",
      "required": true
    }
  },
  "additionalProperties": false
}

The check object is simply whether the provided code/otp_id combination was correct or not.

Performing a check

http --auth :ATIOQWNAIOQIGFVGEXGGCHYMPQAOHNGZ https://api.gauthify.com/v1/check/ \
      unique_id=user_1 \
      otp=123456 \
      otp_id='07e61c512d804bfda6a953ed3cced5ab'

auth_instance.check_token(unique_id="user_1", otp="123456", otp_id="07e61c512d804bfda6a953ed3cced5ab")

auth_instance.check_token(unique_id="user_1", otp="123456", otp_id="07e61c512d804bfda6a953ed3cced5ab")

auth_instance.CheckAuth(string uniqueId = "user_1", string otp = "123456", string otpId = "07e61c512d804bfda6a953ed3cced5ab")

Sample JSON return:

{
    "data": {
        "authenticated": false
    },
    "request_id": "ed40adf67def400f833e220146a14948",
    "server_time": "<timestamp>"
}

Parameters

Parameter	Default	Description
unique_id	REQUIRED	Unique id of user to check
otp	REQUIRED	One time password provided by user
otp_id	Optional	The ID provided from the call to email, sms, or voice

When you send an sms/email/voice the response will include an otp_id. When otp_id is provided with the otp, the authentication will only match against the one in that sent in that sms/email/voice communication. If otp_id is omitted it will match with all non-expired OTPs.

SPECIAL NOTES

Phone Number Format

Phone numbers are expected to be in E.164 format Like +44123456789. In the event they aren’t they will be parsed as US numbers (i.e 213456789 will be parsed as +1213456789)

If you’d like to change default parsing behavior please contact support.

Datetime Format

Datetimes are provided in ISO 8601 format.

Example: 2015-11-05T04:43:11.404905+00:00"

Lang Format

Lang Choices are one of da-DK, en-GB, en-US, fr-FR, de-DE, it-IT, es-ES, sv-SE

Template Tags

Templates created via the Template resource and sent via the template_override have a few template tags you can use including:

• {{ otp }} this replaces the one time password in the template with the generated code, this is generally required.
• {{ app_name }} Your configured application name
• {{ display_name }} the provided display_name of the user
• {{ realm.meta.<var_name> }} variables stored in your realm’s metadata
• {{ user.meta.<var_name> }} variables stored in that users’ metadata
• {{ meta.<var_name> }} meta variables sent as a part of the comm request

Template Defaults

SMS Default: Hi! Here is your one time use code: {{ otp }}. Thanks {{ app_name }}!

Voice Default: Hey there! Your one time use code is, {{ otp }}. I repeat, {{ otp }}. One last time your code is, {{ otp }} , Goodbye!

Email Default:

Hi,

You have requested a one time use code to be able to log into your account.

Your code is: {{ otp }}

This code can be used on a one time basis only, and will be disabled after its use.

Thanks,

{{ app_name }}

ERRORS

Here are the possible API errors:

Http Status	Internal Code	Message
400	400_GENERIC	Bad Request.
401	401	UnAuthorized: Invalid API Key
402	402_API_USER_LIMIT	You have reached the API user limit. Please submit payment to continue.
402	402_EMAIL_DISABLED	Email not enabled in your membership. Please change plan to continue.
402	402_EMAIL_RATE_LIMIT	Can only send email to same person once every 30 seconds.
402	402_SMS_DISABLED	SMS not enabled in your membership. Please change plan to continue.
402	402_SMS_RATE_LIMIT	Can only send SMS to same person once every 30 seconds.
402	402_VOICE_DISABLED	Voice not enabled your membership. Please change plan to continue.
402	402_VOICE_RATE_LIMIT	Can only call the same person once every 60 seconds.
404	404_PAGE_RANGE	This page does not exists.
404	404_TEMPLATE_ID	An object with that template_id not found. Use POST to create new.
404	404_TOKEN	token not found.
404	404_UNIQUE_ID	An object with that unique_id not found. Use POST to create new.
406	406_AUTH_CODE_EMPTY	No auth_code provided in the request.
406	406_DISPLAY_NAME	The display_name provided has unacceptable characters. Use alphanums.
406	406_EMAIL_EMPTY	No email on account and none provided in request.
406	406_EMAIL_INVALID	Email invalid or in incorrect format.
406	406_EMAIL_OVERRIDE	email_override was not parseable as an email
406	406_EXPIRE_OVERRIDE	The expire_override is incorrect, probably not intable
406	406_GROUPS	The group must be a string which is a json list of string/int values. Max len: 4096
406	406_META	The meta must be a json hash/dict of string/int key and values. Max len: 4096
406	406_META_INVALID	Bad meta data or json. Note: All keys must be strings and values strings/bools/floats/ints with a maximum length of 50. You can have a maximum number of 20 key/value pairs. Keys prefixed with gauthify are protected.
406	406_PHONE_EMPTY	No phone number on account and none provided in request.
406	406_PHONE_OVERRIDE	phone_override was not parseable as a phone number
406	406_SMS_BODY_INVALID	The SMS body is too long or bad. Check your template in the settings.
406	406_SMS_NUMBER_INVALID	sms_number invalid or does not have at least 10 digits.
406	406_SUBJECT	The subject must be a string and shorter than 1000
406	406_TEMPLATE_BODY	The template body must contain ’{{ otp }}’ and must be shorter than 12000.
406	406_TEMPLATE_ID	The template_id is empty or not in a good format
406	406_TEMPLATE_LANG	Invalid lang choice. Must be one of: da-DK, en-GB, en-US, fr-FR, de-DE, it-IT, es-ES, sv-SE
406	406_UNIQUE_ID	The unique_id is empty or has unacceptable characters. Use alphanums.
406	406_VOICE_NUMBER_INVALID	voice_number invalid or does not have at least 10 digits.
409	409_EXISTS	Conflict since already exists. Please use PUT or DELETE followed by a POST to re-create object.
500	500_UNDEFINED_ERROR	Unknown error occurred. Please contact [email protected] for help

SUPPORT

Support can be contacted via [email protected] or the email provided in the enterprise licence

IP Whitelisting

It is important to add IP whitelisting for your service, please contact GAuthify with your request origin IPs so they can be whitelisted for requests.

Status Endpoint & Monitoring

There is a live infrastructure test on endpoint api.gauthify.com/status/. Anytime the status code on a request to that endpoint is 200 the website and the backing infrastructure are detected as healthy. Anytime that code is 500 some part of the infrastructure is down.

We also use newrelic and uptimerobot to get deep application insight and performance, health and quality updates.

Emergencies

If a support request is urgent please add [URGENT] to the subject. Please note this triggers a call to an on-call engineer so use only when needed.

Security Problems

If there is a security finding/impact to this service please contact us and add [SECURITY] to the subject. Please note this triggers a call to an on-call engineer so use only when needed.

Config Params

If you’d like to change a configuration on your account please contact support. Config params include

• App name
• Global default expires by channel
• Global default templates by channel
• Etc