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) |
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) |
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
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:
{{ 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