NAV navbar

What is Auth0 Signals

Introduction

Malicious login traffic is detected with Auth0’s Anomaly Detection engine. This helps protect our customers from automated attacks, such as credential stuffing.

The engine consumes an unparalleled number of risk signals, such as domain reputation and breached password detection to understand a source’s risk level.

We refer to this data as Auth0 Signals and make much of it freely available to everyone via API to help you combat automated attacks with adaptive authentication.

What resources are listed?

There are several different types of resources that will grow in time:

Where are the API endpoints servers deployed?

There are multiple servers deployed worldwide in different Cloud regions, scaling up and down automatically to handle peaks and valleys usage. The secure endpoint is:

When you perform a request to this endpoint, thanks to the magic of DNS Anycast and latency-based resolution you will be served with the closest server available.

How to use the API

The access to the API has been developed to be simple, minimalistic and fast. We have followed the Keep it Simple (KISS) approach, with several different ways to access the data.

To use the API you will need an API KEY or TOKEN that you will pass along your request. You need to sign up to get it.

API is restricted by this API KEY. The access is limited to a number of API requests per day. If you exceed that limit in a 24 hour period the service will return a 429 HTTP status code. If you need to make more requests you should consider contacting us and tell us why you need a higher limit. You can know in real time the quota consumed daily from the Dashboard.

There is also an ANONYMOUS PLAN. The platform applies this plan if a developer does not pass any API TOKEN when doing a request. So you can test the API before signing up!

The Administration Dashboard

To enjoy the API and the different services it is necessary for the user to register on our platform. By registering on the platform you have access to the administration dashboard. This administration console allows you to know your consumption and the number of pending requests in the current 24 hours cycle.

Authentication

To authorize with a header parameter, use this code:

# With shell, you can just pass the correct header with each request
curl "https://signals.api.auth0.com" -H "X-Auth-Token: UUID"

To authorize with a query string parameter, use this code:

# With shell, you can just pass the correct header with each request
curl "https://signals.api.auth0.com/?token=UUID"

Make sure to replace UUID with your API KEY.

Auth0 Signals uses an API KEY to allow access to the API. You need to sign up to get one.

Auth0 Signals expects for the API KEY to be included in all API requests made. It can be included as a header or as a query string parameter.

X-Auth-Token: UUID

IP Reputation Analytics

Get full IP address reputation info

Full IP address reputation performs several checks against the IP address given, returning several individual scores per each check, and a global score to summarize them all. The checks are:

These three checks (IP address blacklist, Domain blacklist and IP address historical blacklist) are summarized and returned as a global score for the IP address. The possible values are:

This API call also returns detailed information about the IP address from different sources:

$ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://signals.api.auth0.com/v2.0/ip/<IP>"

The response can be:

{
    "fullip": {
        "geo": { ... },
        "hostname": "abts-tn-static-035.5.165.122.airtelbroadband.in",
        "baddomain": {
            "domain": {
                "blacklist": [],
                "blacklist_mx": [],
                "blacklist_ns": [],
                "mx": [],
                "ns": [],
                "score": 0
            },
            "ip": {
                "address": "",
                "blacklist": "",
                "is_quarantined": false,
                "score": 0
            },
            "source_ip": {
                "address": "71.152.251.222",
                "blacklist": [],
                "is_quarantined": false,
                "score": 0
            },
            "score": 0
        },
        "badip": {
            "score": 0,
            "blacklists": []
        },
        "history": {
            "score": -1,
            "activity": [
                {
                    "ip": "122.165.5.35",
                    "timestamp": 1537000113218,
                    "command": "rem",
                    "blacklists": "",
                    "blacklist_change": "UCEPROTECT-LEVEL1"
                },
                ...
            ],
            "score_1day": false,
            "score_7days": false,
            "score_30days": true,
            "score_90days": true,
            "score_180days": true,
            "score_1year": true
        },
        "score": -1,
        "whois": { ... }
    }
}

HTTP Request

GET https://signals.api.auth0.com/v2.0/ip/<IP>

Header Parameters

Parameter Mandatory Description
X-Auth-Token Yes API KEY of the owner.

QueryString Parameters

Parameter Mandatory Description
token Yes API KEY of the owner.
timestamp No UNIX time in seconds to filter the search in the database. If ignored, then current UNIX time is taken.
page No Page number to paginate the result. Always start at 1. If ignored, then search for page one.
items No Number of items per page. Can be in the range of 5 to 200. If ignored, then return 5 items.
callback No Function to invoke when using JSONP model.

URL Parameters

Parameter Description
IP The IP to look up in the system.

Response

The status code of the response will be a 200 HTTP code if everything is ok and it will also return the following JSON structure.:

Parameter Description
fullip 'FullIP' JSON object cointaining all the information gathered from the different sources.

Check if an IP belongs to any abusers' blacklist

Auth0 Signals tracks multiple abuse blacklists and consolidates them in a single database you can look up with our minimalist API.

$ curl -i -H "X-Auth-Token: UUID" -X GET "https://signals.api.auth0.com/badip/<IP>"

The response can be:

HTTP/1.1 200 OK
CONTENT-TYPE: text/plain; charset=utf-8
CONTENT-LENGTH: 7
DATE: X
SERVER: Python/3.5 aiohttp/0.21.6

or

HTTP/1.1 404 Not Found
CONTENT-TYPE: text/plain; charset=utf-8
CONTENT-LENGTH: 18
DATE: X
SERVER: Python/3.5 aiohttp/0.21.6

This endpoint returns if the IP belongs to any list with the HTTP status code in the response.

HTTP Request

GET https://signals.api.auth0.com/badip/<IP>

Header Parameters

Parameter Mandatory Description
X-Auth-Token No API KEY of the owner.

QueryString Parameters

Parameter Mandatory Description
token No API KEY of the owner.
callback No Function to invoke when using JSONP model.

URL Parameters

Parameter Description
IP The IP to look up in the system.

Response

The response can be a 200 or 404 HTTP code if everything is ok:

Get all blacklists an IP belongs to

$ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://signals.api.auth0.com/badip/<IP>"

The response can be:

{
    "blacklists": ["STOPFORUMSPAM-180", "STOPFORUMSPAM-30", "STOPFORUMSPAM-7", "STOPFORUMSPAM-365", "STOPFORUMSPAM-90"]
}

or

Resource Not found

If a developer wants to know what blacklists contain the IP passed as argument, she needs to pass to curl an extra argument with information about the Content type as *application/json***\:

HTTP Request

GET https://signals.api.auth0.com/badip/<IP>

Header Parameters

Parameter Mandatory Description
X-Auth-Token No API KEY of the owner.
Accept Yes application/json

QueryString Parameters

Parameter Mandatory Description
token No API KEY of the owner.
callback No Function to invoke when using JSONP model.

URL Parameters

Parameter Description
IP The IP to look up in the system.

Response

The status code of the response can be a 200 or 404 HTTP code if everything is ok, but it will also return the following JSON structure if status code is 200:

Parameter Description
blacklists Array with a list with the Identifiers of each blacklist.

Get all abusers' blacklist a set of IP belong to (Bulk request)

$ curl -H "Accept: application/json" -H "X-Auth-Token: UUID" -X GET "https://signals.api.auth0.com/badip_batch/<IP1>,<IP2>...<IPn>"

The response can be:

{
    "response": [
        {
            "ip": "8.8.8.8",
            "blacklists": []
        },
        {
            "ip": "212.231.122.12",
            "blacklists": []
        },
        {
            "ip": "1.2.3.4",
            "blacklists": ["STOPFORUMSPAM-180", "STOPFORUMSPAM-30", "STOPFORUMSPAM-7", "STOPFORUMSPAM-365", "STOPFORUMSPAM-90"]
        }
    ]
}

A developer can save time and rate-limit restrictions if she passes a list of comma separated IP in the QueryString. She will get the blacklists for each IP in the response. If the IP is not well formed it will return nothing for that IP, but will perform the lookup for the rest of the valid IP addresses.

HTTP Request

GET https://signals.api.auth0.com/badip_batch/<IP>

Header Parameters

Parameter Mandatory Description
X-Auth-Token No API KEY of the owner.
Accept No application/json

QueryString Parameters

Parameter Mandatory Description
token No API KEY of the owner.
callback No Function to invoke when using JSONP model.

URL Parameters

Parameter Description
IP1,IP2,...IPn The comma separated list of IP to look up in the system.

Response

The status code of the response can be a 200 if everything is ok, but it will also return the following JSON structure:

Parameter Description
response Array with a list with the blacklists for each IP.

Objects

IP

The ip score contains the information of looking up the IP in the blacklists.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' IP. Neutral or positive means it's a 'clean' IP.
blacklist Array containing the blacklists where the IP was found.

domain

The domain object contains the information used in the scoring algorithm.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positivo means it's a 'clean' domain.
domain JSON structure containing the 'domainname score' object as result of the analysis of the domains.
ip JSON structure containing the 'ip score' object as result of the analysis of the IP of the domain.
source_ip JSON structure containing the 'ip score' object as result of the analysis of the IP origin of the request.

email

The email object contains the information used in the scoring algorithm.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
domain JSON structure containing the 'domainname score' object as result of the analysis of the domains.
ip JSON structure containing the 'ip score' object as result of the analysis of the IP of the domain.
source_ip JSON structure containing the 'ip score' object as result of the analysis of the IP origin of the request.
address JSON structure containing the 'address score' object as result of the analysis of the email.
smtp JSON structure containing the 'smtp score' object as result of the analysis of the email service.
freemail JSON structure containing the 'freemail score' object as result of the analysis of the email provider.
email JSON structure containing the 'email-blacklist score' object as result of the look up in the email blacklists.
disposable JSON structure containing the 'disposable score' object as result of the analysis of the email provider.

geoip

The geoip object contains the information used in Geolocation of an IP.

Parameter Description
longitude Longitude where the IP has been found
latitude Latitude where the IP has been found
hostname Name of the host resolved from the IP
address IPv4 or IPv6 address of the request
continent 2 letter code of the continent.
country ISO 3166-1 Country code.
region Name of the region, by default the english translation in 'region_names'.
city Name of the city, by default the english translation in 'city_names'.
postal Postal code or Zip code
time_zone Time zone of the location
accuracy_radius The approximate radius in kilometers around the latitude and longitude for the geographical entity. -1 if unknown.
continent_geoname_id Id of the continent in the geonames.org database. -1 if the continent cannot be geolocated.
country_geoname_id Id of the country in the geonames.org database. -1 if the country cannot be geolocated.
region_geoname_id Id of the region in the geonames.org database. -1 if the region cannot be geolocated.
city_geoname_id Id of the city in the geonames.org database. -1 if the city cannot be geolocated.
continent_names JSON structure containing the different names of the continent in different languages. Languages are in ISO 639-1. Empty if continent cannot be geolocated.
country_names JSON structure containing the different names of the country in different languages. Languages are in ISO 639-1. Empty if country cannot be geolocated.
region_names JSON structure containing the different names of the region in different languages. Languages are in ISO 639-1. Empty if region cannot be geolocated.
city_names JSON structure containing the different names of the city in different languages. Languages are in ISO 639-1. Empty if city cannot be geolocated.
as JSON structure containing the 'as' object.

as

The AS object contains the information of Autonmous System

Parameter Description
asn AS number
name name of the AS
country ISO 3166-1 Country code
networks Array with the lists of networks of the AS obtained from BGP tables.

asv2

The AS object contains the information of Autonmous System for the v2.0 of the API endpoint.

Parameter Description
asn AS number
name name of the AS
asn_description Full description of the AS
asn_date Date when the AS was registered
asn_registry Local registry that maintains the AS information.
country ISO 3166-1 Country code
networks Array with the lists of networks of the AS obtained from BGP tables.
networks_v4 Array with the lists of ipv4 cidr information. See AS_NETWORK object.
networks_v6 Array with the lists of ipv6 cidr information. See AS_NETWORK object.

as-network

The AS object that contains the information of the CIDR block and the maintainer.

Parameter Description
cidr IPv4 or IPv6 prefix of a block managed by the AS.
description Human readable description of the object.
maintainer Who is the maintainer of the object. It can reference other AS or itself.
updated Who made the last change and when.

domainname score

The domainname score contains the information of testing different subdomains of the main root domain: NS records, MX records and domain blacklists.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
blacklist_ns Array containing the blacklists where the NS domains were found.
blacklist_mx Array containing the blacklists where the MX domains were found.
blacklist Array containing the blacklists where the domain was found.
mx Array with the hosts found in the MX records.
ns Array with the hosts found in the NS records.

ip score

The ip score contains the information of looking up the IP in the blacklists.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' IP. Neutral or positive means it's a 'clean' IP.
blacklist Array containing the blacklists where the IP was found.
is_quarantined If the IP has been added by the user to the quarantine lists.
address IPv4 or IPv6 resolved.

address score

The address score contains the information of checking the format of the email.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
is_role The email has the format of a role-based-address. It's not common to allow registration with role-based-addresses.
is_well_formed The email is compliant or not with the standards and could cause issues in some systems.

smtp score

The smtp score contains the information obtained after testing the remote inbox where the email is hosted.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
exist_mx The SMTP service is reachable using the hosts in the MX records.
exist_address The SMTP service recognizes the email address.
exist_catchall The SMTP service implements a catch-all email feature.
graylisted The SMTP service implements a graylisting feature, so the data in this object should be analyzed before considering it valid.
timedout The SMTP service timed out before completing all the tests. Hence, the data in this object should be considered not valid.

freemail score

The freemail score contains the information of looking up the domain in the lists of Free Email Service Providers.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
is_freemail The domain has been found in any Free Email Service Provider list.

disposable score

The disposable score contains the information of looking up the domain in the lists of Disposable Email Addresses Providers.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' domain. Neutral or positive means it's a 'clean' domain.
is_disposable The domain has been found in any Disposable Email Address Providers list.

email score

The email score contains the information of looking up the email in the blacklists.

Parameter Description
score Number describing the result of the algorithm. Negative means 'suspicious' or 'bad' email. Neutral or positive means it's a 'clean' email.
blacklist Array containing the blacklists where the email was found.

transaction ip

The transaction ip object contains information about what action was performed on the blacklists/blacklists in the database.

Parameter Description
timestamp The UNIX time in seconds when the transaction was performed.
command 'add' or 'rem'. Type of transaction in the database: ADD to the blacklist or REMove of the blacklist.
ip IP address of the transaction
blacklist_change Blackist added or removed thanks to the transaction.
blacklists List of blacklists after the execution of the command and the blacklist change.

transaction domain

The transaction domain object contains information about what action was performed on the blacklists in the database.

Parameter Description
timestamp The UNIX time in seconds when the transaction was performed.
command 'add' or 'rem'. Type of transaction in the database: ADD to the blacklist or REMove of the blacklist.
domain Domain of the transaction
blacklist_change Blackist added or removed thanks to the transaction.
blacklists List of blacklists after the execution of the command and the blacklist change.

transaction email

The transaction email object contains information about what action was performed on the blacklists in the database.

Parameter Description
timestamp The UNIX time in seconds when the transaction was performed.
command 'add' or 'rem'. Type of transaction in the database: ADD to the blacklist or REMove of the blacklist.
email Email of the transaction
blacklist_change Blackist added or removed thanks to the transaction.
blacklists List of blacklists after the execution of the command and the blacklist change.

whois

Contains many nested lists and objects, detailed below.

Parameter Description
query The IP address
asn Globally unique identifier used for routing information exchange with Autonomous Systems.
asn_cidr Network routing block assigned to an ASN.
asn_country_code ASN assigned country code in ISO 3166-1 format.
asn_date ASN allocation date in ISO 8601 format.
asn_registry ASN assigned regional internet registry.
asn_description The ASN description
network The assigned network for an IP address. May be a parent or child network. See Network object.
entities list of object names referenced by an RIR network. Map these to the objects keys.
objects The objects (entities) referenced by an RIR network or by other entities (depending on depth parameter). Keys are the object names with values as Object.

whois network

The parameters mapped to the network in the objects list within the whois object.

Parameter Description
cidr Network routing block an IP address belongs to.
country Country code registered with the RIR in ISO 3166-1 format.
end_address The last IP address in a network block.
events List of events. See Events object.
handle Unique identifier for a registered object.
ip_version IP protocol version (v4 or v6) of an IP address.
links HTTP/HTTPS links provided for an RIR object.
name The identifier assigned to the network registration for an IP address.
notices List of notice objects. See Notices object.
parent_handle Unique identifier for the parent network of a registered network.
remarks List of remark (notice) dictionaries. See Notices object.
start_address The first IP address in a network block.
status List indicating the state of a registered object.
type The RIR classification of a registered network.

whois object

The parameters mapped to the object (entity) in the objects list within the whois.

Parameter Description
contact Contact information registered with an RIR object. See Object Contact.
entities List of object names referenced by an RIR object. Map these to other objects keys.
events List of event dictionaries. See Events object.
events_actor List of event (no actor) dictionaries. See Events object.
handle Unique identifier for a registered object.
links List of HTTP/HTTPS links provided for an RIR object.
notices List of notice dictionaries. See Notices object.
remarks List of remark (notice) dictionaries. See Notices object.
roles List of roles assigned to a registered object.
status List indicating the state of a registered object.

whois object contact

The contact information registered to an RIR object. This is the contact key contained in Object.

Parameter Description
address List of contact postal address dictionaries. Contains key type and value.
email List of contact email address dictionaries. Contains key type and value.
kind The contact information kind (individual, group, org).
name The contact name.
phone List of contact phone number dictionaries. Contains key type and value.
role The contact’s role.
title The contact’s position or job title.

whois event

Common to lists of events in the registry.

Parameter Description
action The reason for an event.
timestamp The date an event occured in ISO 8601 format.
actor The identifier for an event initiator (if any).

whois notice

Information contained in notices and remarks.

Parameter Description
title The title/header for a notice.
description The description/body of a notice.
links list of HTTP/HTTPS links provided for a notice.

fullip

Information gathered from different sources to describe the reputation of the IP Address.

Parameter Description
geo IP Geolocation object as described in GeoIP
hostname String with the name of a hostname result of a reverse DNS lookup on the IP Address.
baddomain The Domain object contains the information obtained in the scoring algorithm of the hostname.
badip The IP object contains the information obtained in the scoring algorithm of the IP address.
history List of transactions as objects History IP in the IP address blacklist database and the scoring.
whois Full WHOIS information as described in the object WHOIS
score Number describing the result of summarizing each individual scores.

history ip

List of transactions in the blacklist database and the scoring based on when it was inserted.

Parameter Description
score Number describing the result of the algorithm. Negative means the IP was add to any blacklist in the specified time range.
activity List of Transaction IP objects with the activity in the database.
score_1day True if the IP was added in any blacklist in the last 24 hours.
score_7days True if the IP was added in any blacklist in the last 7 days.
score_30days True if the IP was added in any blacklist in the last 30 days.
score_90days True if the IP was added in any blacklist in the last 90 days.
score_180days True if the IP was added in any blacklist in the last 180 days.
score_1year True if the IP was added in any blacklist in the last 365 days.

blacklist

Details about a given blacklist.

Parameter Description
group Sub-group to classify the blacklists.
refresh How often the list is updated. It's a human readable text.
last_update When was the last time the blacklist was updated. Expressed in seconds since 00:00:00 UTC, 1 January 1970 (Unix Time).
visibility If this list is Public or Private.
site The website or internet endpoint where the list was obtained.
type Blacklist type: badip, baddomain or bademail.
description A human readable description of what is this list and its purpose.
source Generic name of the data source.
name Human readable name of the list.
count Number of items in the list.
problem A human readable description of why a user should use the list.
enabled Internal information. Should always be Enabled for end users.

blackliststats

Statistics of the blacklists.

Parameter Description
badip A blackliststatsinfo object with the number of items and lists of type badip.
baddomain A blackliststatsinfo object with the number of items and lists of type baddomain.
bademail A blackliststatsinfo object with the number of items and lists of type bademail.

blackliststatsinfo

Information detail of the blacklists statistics.

Parameter Description
items Number of items in the chosen type.
lists Number of lists in the chosen type.

last_badip_log

Number of IP addresses processed in the last hour, 24 hours and 7 days.

Parameter Description
last_hour An integer with the number of IP addresses processed in the last 60 minutes.
last_24_hours An integer with the number of IP addresses processed in the last 24 hours.
last_7_days An integer with the number of IP addresses processed in the last 7 days.