Introduction to the Sqreen API
The Sqreen API allows you to tap into our extensive knowledge base to discover security risks hiding in your own data. Find out whether that email address is from an anonymizing service, or that IP address is a Tor exit point. You can even find out if the address has been implicated in a past security attack.
For example, you might want to know whether ChunkLover53@aol.com represents a risk, and should be barred from signing up for your service. You can query the Sqreen API to discover that this user has a high risk score.
{
"email": "ChunkyLover53@aol.com",
"risk_score": 80,
"is_known_attacker": true,
"high_risk_security_events_count": 3,
"security_events_count": 15,
"is_disposable": false,
"is_email_malformed": false,
"is_email_harmful": false
}
Sound interesting? Getting started requires a few more steps.
Do I need an account?
Yes. To use the APIs, you'll need to create account with Sqreen and register a new app. Don't worry if you don't have a web app running somewhere that you want to monitor, you can get started quickly with the API by selecting the "Developer Sandbox" app type. The Developer Sandbox lets you get started building with the Sqreen API without committing to install the Sqreen Agent into a production web app. The Developer Sandbox is completely free, and although rate-limited, can be used for standalone access to the API for as long as you want.
I am already a Sqreen customer
If you already have a Sqreen account, you can either create a new Developer Sandbox app to get started playing with the Sqreen API, or you can use the API key we have generated for any apps you already have registered. Click on the API tab for any existing apps to reveal the API key.
At the moment, the Screen API comprises two endpoints—one for learning more about email addresses, and one for learning more about IP addresses, both detailed below.
In the future, however, we have planned more ways for your app to integrate into the Sqreen service. We would love to hear your feedback on the API, and the future: Drop us a line and tell us what you think.
All API endpoints are served over HTTP, and require encryption with SSL.
All API endpoints return JSON objects (although we'd certainly consider support other formats).
API Keys
Ready to get started learning about the Sqreen API? You can read the documentation without an account, but playing with the APIs requires an API key.
Authentication
All Sqreen API endpoints require authentication with a Sqreen API key. You can find instructions above for getting your key.
Once you have an account, you can retrieve your API key from the API tab in your account dashboard. You'll want to copy it so you can paste it into the interactive documentation below.
To authenticate API calls in your own code, add a header to your HTTP request called X-API-Key whose value is your is API key. For example, if your API key is TODO_API_KEY_HERE, you would add the following header to your request:
X-API-Key: TODO_API_KEY_HERE
With curl, this would look like:
curl https://api.sqreen.io/v1/ips/8.8.8.8 -H "X-API-Key: TODO_API_KEY_HERE"
Attempts to call the Sqreen API without a valid API key specified in this way will be denied with a 401 error.
Swagger
All Sqreen API endpoints have Swagger definitions available. Swagger—now called OpenAPI—is a structured way to describe API endpoints readable by computers and developers alike. It's pretty nifty.
/emails
Uncover security risks hiding in email addresses
Use this endpoint to uncover more information about an email address. Sqreen has an extensive database of known attackers, as well as analysis on an email address's origins. Discover whether this email address is from an anonymizing service, or was used in an attack, and use this data to make policy decisions based on how risky we assess the email address to be.
email
string
The email address queried.
risk_score
number
The assessed risk that this email address is being used by a malevolent actor.
Values range from 0 to 100. Anything greater than 80 is really bad and should be dropped; anything greater than about 40 is worth flagging and keeping an eye on.
is_email_harmful
boolean
Does the email address itself pose a direct security risk? E.g., does the email address contain embedded JavaScript?
is_known_attacker
boolean
Was this email address used as part of a security attack?
high_risk_security_events_count
number
The number of high-risk security events (e.g. SQL injection attacks) involving this email address.
security_events_count
number
The number of all security events (both high-risk and low-risk) involving this email address.
is_disposable
boolean
Does this email's domain belong to a known vendor of disposable, temporary, or anonymized email addresses?
is_email_malformed
boolean
Is the email malformed according to RFC 5322?
/ips
Uncover security risks hidden in IP addresses
Use this endpoint to uncover more information about an IP address. Sqreen has an extensive database of known attackers, as well as analysis on who or what an IP address belongs to. Discover whether this IP address is a Tor exit point or was used in an attack, and use this data to make policy decisions based on how risky we assess the IP address to be.
ip
string
The IP address queried.
ip_version
number
The version of the IP address queried. Either 4 or 6.
risk_score
number
The assessed risk that this IP address is being used by a malevolent actor.
Values range from 0 to 100. Anything greater than 80 is really bad and should be dropped; anything greater than about 40 is worth flagging and keeping an eye on.
is_known_attacker
boolean
Was this IP address used as part of a security attack?
high_risk_security_events_count
number
The number of high-risk security events (e.g. SQL injection attacks) originating from this IP address.
security_events_count
number
The number of all security events (both high-risk and low-risk) originating from this IP address.
ip_geo
object
The geographical location associated with this IP address.
ip_geo.latitude
number
The latititude of the location.
ip_geo.longitude
number
The longitude of the location.
ip_geo.country_code
string
The ISO ALPHA-3 Code for the country that this location exists within.
is_datacenter
boolean
Does this IP address belong to a known datacenter, such as AWS or Google Cloud?
is_vpn
boolean
Does this IP address belong to a known VPN?
is_proxy
boolean
Does this IP address belong to a known proxy server?
is_tor
boolean
Is this IP address a known Tor exit point?
Integrations with Third-Party Tools
Here you can find a list of contributed integrations of the Sqreen API with other services that you can use in your own apps.
Devise is a popular authentication library for Rails. Now you can use the Sqreen API to screen out risky signups to your Rails app. Sqreen Enricher for Devise passes you metadata from the Sqreen API about email and IP addresses, and allows you to configure rules around that metadata to reject signups based on their risk to your app's security.
And you…?
Built something cool with the Sqreen API you'd like to share with the world? We'd love to help! Drop us a line, and we'll include your project right here.