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.
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="18.97.14.83"
$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'] = '18.97.14.83';
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= '18.97.14.83';
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': '18.97.14.83'
}
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'] = '18.97.14.83'
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:
https://api.zenlogin.co/v1/applications/appl0123456789/logins/checks
your_secret_key
usr12345
name@website.com
Mozilla/5.0 (Windows NT 6.1; rv:74.0) Gecko/20100101 Firefox/74.0
18.97.14.83
The following arguments are required for all login checks:
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.identity_email_address
- This is the email address we'll send suspicious login notifications to.
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).
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.
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.0
.
0
.
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"
}
]
}
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.
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