NAV
HTTP Ruby Python C#

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='[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='[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:

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_override='[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:

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