Quick Start

How to get started with Zenlogin!

This page will help you get started with Zenlogin! All the important stuff is documented here, but should you have any questions, always feel free to reach out to: support@zenlogin.co.

API Request Example

We think the best way to explain something is to start with an example. Below, you'll find a sample call to Zenlogin using curl. We know that curl is probably not the language you'll use, but we show it below because it's the most clear (you can copy+paste the code below into your Terminal to see what a sample response looks like). 

curl https://api.zenlogin.co/v1/applications/appl0123456789/logins/checks \

  --header "X_API_SECRET_KEY: your_secret_key" \

  --data identity_key="usr12345" \

  --data identity_email_address="name@website.com" \

  --data user_agent="Mozilla/5.0 (Windows NT 6.1; rv:74.0) Gecko/20100101 Firefox/74.0" \

  --data ip_address="3.133.144.217"

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.zenlogin.co/v1/applications/appl0123456789/logins/checks');
$postData = array();
$postData['identity_key'] = 'usr12345';
$postData['identity_email_address'] = 'name@website.com';
$postData['user_agent'] = 'Mozilla/5.0 (Windows NT 6.1; rv:74.0) Gecko/20100101 Firefox/74.0';
$postData['ip_address'] = '3.133.144.217';
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'X_API_SECRET_KEY: your_secret_key'
));
$response = curl_exec($ch);
$response = json_decode($response, true);
curl_close($ch);

const axios = require('axios');
const endpoint = 'https://api.zenlogin.co/v1/applications/appl0123456789/logins/checks',
  postData = {},
  options = {};
postData.identity_key = 'usr12345';
postData.identity_email_address = 'name@website.com';
postData.user_agent = 'Mozilla/5.0 (Windows NT 6.1; rv:74.0) Gecko/20100101 Firefox/74.0';
postData.ip_address= '3.133.144.217';
options.headers = {};
options.headers.X_API_SECRET_KEY = 'your_secret_key';
axios.post(endpoint, postData, options).then(function(response) {
  console.log(response.data);
}).catch(function(error) {
  console.error(error.response.data);
});

import requests
url = 'https://api.zenlogin.co/v1/applications/appl0123456789/logins/checks'
postData = {
  'identity_key': 'usr12345',
  'identity_email_address': 'name@website.com',
  'user_agent': 'Mozilla/5.0 (Windows NT 6.1; rv:74.0) Gecko/20100101 Firefox/74.0',
  'ip_address': '3.133.144.217'
}
headers = {'X_API_SECRET_KEY': 'your_secret_key'}
response = requests.post(url, data=postData, headers=headers)
print response.content

require 'uri'
require 'net/http'

uri = URI('https://api.zenlogin.co/v1/applications/appl0123456789/logins/checks')
req = Net::HTTP::Post.new(uri.path)
req['X_API_SECRET_KEY'] = 'your_secret_key'
postData = {}
postData['identity_key'] = 'usr12345'
postData['identity_email_address'] = 'name@website.com'
postData['user_agent'] = 'Mozilla/5.0 (Windows NT 6.1; rv:74.0) Gecko/20100101 Firefox/74.0'
postData['ip_address'] = '3.133.144.217'
req.set_form_data(postData);

https = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true

response = https.request(req)
puts response.body

In the API call above, you can see that there are six unique (and required) properties:

  1. The API endpoint: https://api.zenlogin.co/v1/applications/appl0123456789/logins/checks
    This can be found on your API Credentials page.
  2. The account's secret key: your_secret_key
    This can be found on your API Credentials page.
  3. A unique key of the user logging into your product: usr12345
  4. The email address of the user logging into your product: name@website.com
  5. The User Agent of the user when they log into your product: Mozilla/5.0 (Windows NT 6.1; rv:74.0) Gecko/20100101 Firefox/74.0
  6. The IP Address of the user when they log into your product: 3.133.144.217

Required Arguments

The following arguments are required for all login checks:

  1. identity_key - This is a unique identifying key (or id) for the user you're performing a check against. This shouldn't be their email address, since email addresses can (and do) change.

    A hashed-version of this argument is used to check and detect suspicious logins, and therefore this should never change for a user.
  2. identity_email_address - This is the email address we'll send suspicious login notifications to.
  3. user_agent - This is the User Agent of the user when they log into your service. We use this to detect possible threats (eg. bots or spiders), as well as to detect previously identified logins (among other things).
  4. ip - This is the IP address of the user when they log into your service. This is crucial, since it allows us to detect anomalies in login behaviour, as well as possible threats.

Optional Arguments

  • identity_first_name - This can be a string that represents the first name of the user that is logging into your service. This value can be used as a variable in email notifications that are sent.
  • identity_last_name - This can be a string that represents the last name of the user that is logging into your service. This value can be used as a variable in email notifications that are sent.
  • identity_full_name - This can be a string that represents the full name of the user that is logging into your service. This value can be used as a variable in email notifications that are sent.
  • req_process - This can be either a 0 or 1 integer that represents whether this login check should be processed.

    Use case #1: You're logging into one of your user's accounts for testing/security purposes, and you don't want to trigger a login check for their account. In that case, pass along a value of 0.

    Use case #2: You don't want requests to be processed in your local or development environments. In that case, pass along a value of 0.

API Response Examples

Zenlogin follows the JSON:API spec for our API response. Our response will always have the content type application/json and be formatted to be human-readable (rather than minified).

Below you'll find an example of a response you'll get when making requests to the Zenlogin API: 

{
  "data": {
    "id": "req_jkferjk33ufueeh34838ifjk33o3io43",
    "timestamp": 1709574876
  }
}
  • id - This property represents a unique ID associated with the login check.
  • timestamp - This property represents the unix timestamp that the API request was received.

Below you'll find a sample error response: 

{
  "errors": [
    {
      "code": "3003",
      "detail": "Invalid *application_key* URL param: appl01234567891"
    }
  ]
}

Error Handling

Errors happen, so we try to do our best to explain to you in each API response what may have gone wrong. This is done by returning an error code and message. As such, we recommend that when you make API calls to Zenlogin, you check the HTTP status code, and anytime it's not a value of 200, you log that for possible investigation later.

Learn more about our Error Handling and specific error codes.

Languages Supported

Like any good API, Zenlogin is language agnostic. That being said, we've put together examples for 5 popular programming langauges. These include:

Since Zenlogin is an API, you can use it in whatever development environment you're working in. If you have examples in your specific language or framework, please send them to us so we can include them: support@zenlogin.co

Jump to