Documentation / API Reference
Looking for the client?
If you are looking to protect your PBX or SIP server without programming, you should use the free APIBAN client to automatically block traffic.
APIBAN API Reference
REST API for sharing IP addresses sending unwanted SIP and HTTP traffic.
APIBAN helps prevent unwanted SIP traffic by identifying addresses of known bad actors before they attack your system. Bad actors are collected through globally deployed honeypots and curated by LOD/APIBAN.
In the videos section, you can learn about APIBAN by watching a presentation (or two).
APIBAN is made possible by the generosity of our sponsors.
Block/Identify Traffic
This API allows you to integrate and interact with APIBAN data.
The data is provided in standard JSON responses and use HTTP Status Codes to help determine results.
NOTE: If you are looking to protect your PBX or SIP server without programming, you should use the free APIBAN client to automatically block traffic.
Introduction
To use the APIBAN API, you will need to first obtain an API KEY. The API KEY is used for all API requests.
NOTE API KEYs are limited to one per user/email. If your organization needs multiple keys, please contact LOD.
APIBAN deploys honeypots worldwide. These honeypots collect the IP addresses of systems sending unwanted traffic to SIP or HTTP servers. The addresses are currated by APIBAN and then made available via API.
IP addresses, once added, remain "active" for 7 days and then can be reactivated immediately (many are reactivated within minutes). Users can check the SIP dataset, the HTTP dataset, or a combined SIP/HTTP dataset.
Data from the API is provided in standard JSON responses and uses HTTP Status Codes to help determine results.
The API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.
Base URL
https://apiban.org/api/
Did you know that we have integration examples for Kamailio, Homer, OpenSIPS, and more at our GitHub page?
Authentication
Authentication has changed!
Authentication with the API is made through the API KEY. If having trouble receiving an API KEY or if an API KEY needs to be replaced, please contact our support team. Requests to the API are limited to 11 requests in 2 minutes.
Authentication is made using your APIKEY in a Bearer Authorization Header.
Authorization: Bearer [APIKEY]
Where [APIKEY] is your APIKEY. Example authentication errors received from the API:
| Response | JSON |
|---|---|
| 403 | {"ipaddress":"none", "ID":"unauthorized"} |
| 429 | {"ipaddress":"rate limit exceeded", "ID":"unauthorized"} |
curl https://apiban.org/api
-H 'Authorization: Bearer 123456789101112abcdefg'
-H 'Content-Type: application/json'
Errors
The API will return non-2xx http status codes and descriptive responses when able to do so. Examples include:
| Code | Summary | JSON |
|---|---|---|
| 400 | Often used to indicated no matching results | {"ipaddress":"no new bans", "ID":"none"} |
| 403 | unauthorized | {"ipaddress":"none", "ID":"unauthorized"} |
| 404 | used within check for an ip address that is not blocked | {"ipaddress":"ok", "ID":"0"} |
| 429 | rate limit exceeded | {"ipaddress":"rate limit exceeded", "ID":"unauthorized"} |
| 503 | server error | {"error":"gK10", "description":"an internal error occurred"} |
Core Resources
Core resources utilize the get and check calls; both hitting the api resource shown in Base URL.
Get
Get is an object returning banned ip addresses in batches of 250. An ID is provided to use when pulling the next batch. If no ID is passed, the first 250 addresses (oldest first) will be provided.
- Method: POST
- Available data sets: sip, http, all
| Parameter | Required | Type | Comments |
|---|---|---|---|
| set | Yes | string | Can be sip, http, all |
| id | No | string | id represents the last id received |
curl https://apiban.org/api/get
-X POST
-H 'Authorization: Bearer 123456789101112abcdefg'
-H 'Content-Type: application/json'
-d '{"set":"all", "id":"7894354"}'
200
{"ipaddress":["1.2.3.4","1.2.3.5"], "ID":"9876543210"}
400
{"ipaddress":["no new bans"], "ID":"none"}
Check
Check is an object returning the status of a specific, single IP address. A 2xx indicates a ban and a 404 indicates the ipaddress is not banned.
When checking the IP address status, the check can be run against a single set of sip or http.
- Method: POST
- Available data sets: sip, http
| Parameter | Required | Type | Comments |
|---|---|---|---|
| ipaddress | Yes | string | Single IP address to be checked |
| set | Yes | string | Can be sip or http |
curl https://apiban.org/api/check
-X POST
-H 'Authorization: Bearer 123456789101112abcdefg'
-H 'Content-Type: application/json'
-d '{"ipaddress":"1.1.1.1", "set":"sip"}'
200
{"ipaddress":"blocked", "ID":"9876543210"}
404
{"ipaddress":"ok", "ID":"0"}
IPset
IPsets (lists of IPs) can be used by many firewalls, iptables, and appliances (such as pfsense, opnsense, etc.) to block unwanted traffic to your network.
IPset uses GET requests with Authorization handled by passing your APIKEY in the uri, such as:
https://apiban.org/ipset/[APIKEY]/list
where [APIKEY] is replaced with your APIKEY.
Please note that this resourse uses ipset and not the api resource.
List
List returns a plain text ipset with control id, record count, and IPs (listed in age order from oldest to most recent). List only checks the sip data set.
- Method: GET
- Available data set: sip
curl https://apiban.org/ipset/123456789101112abcdefg/list
200 plain text document
403
{"ipaddress":"none", "ID":"unauthorized"}
429
{"ipaddress":"rate limit exceeded", "ID":"unauthorized"}
503
{"error":"gK10", "description":"an internal error occurred"}
List All
Listall returns a plain text ipset with control id, record count, and IPs (sorted by IP address). Listall returns a combined list of the sip and http data sets.
- Method: GET
- Available data set: all
curl https://apiban.org/ipset/123456789101112abcdefg/listall
200 plain text document
403
{"ipaddress":"none", "ID":"unauthorized"}
429
{"ipaddress":"rate limit exceeded", "ID":"unauthorized"}
503
{"error":"gK10", "description":"an internal error occurred"}
Cisco
Cisco returns a plain text Cisco formatted list with a deny statement for each IP address (listed in age order from oldest to most recent). The cisco call uses the sip data set.
- Method: GET
- Available data set: sip
curl https://apiban.org/ipset/123456789101112abcdefg/cisco
200 plain text document
403
{"ipaddress":"none", "ID":"unauthorized"}
429
{"ipaddress":"rate limit exceeded", "ID":"unauthorized"}
503
{"error":"gK10", "description":"an internal error occurred"}
Juniper
Juniper returns a plain text Juniper formatted list with a set statement for each IP address (listed in age order from oldest to most recent). The juniper call uses the sip data set.
- Method: GET
- Available data set: sip
curl https://apiban.org/ipset/123456789101112abcdefg/juniper
200 plain text document
403
{"ipaddress":"none", "ID":"unauthorized"}
429
{"ipaddress":"rate limit exceeded", "ID":"unauthorized"}
503
{"error":"gK10", "description":"an internal error occurred"}
Sponsors
APIBAN is a free service thanks to our generous sponsors.
License / Warranty
The APIBAN API is provided in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Software provided by APIBAN through our GitHub Repositories is provided in the hope that it will be useful, but WITHOUT ANY WARRANTY. The specific software's license is provided within the respository.
Getting Help
Help is provided by LOD and an APIBAN room is available on the LOD Matrix homeserver.
Open Source
APIBAN (LOD, and Palner) greatly values and supports open source software.
There are many ways you can participate in open source software, including:
- financial support
- reviewing, writing, updating code
- reviewing, adding, editing documentation
- evangelism
Open Source Used by APIBAN
- Linux — powers our servers and honeypots
- Kamailio — powers our honeypots
- Golang — powers the API
- Redis — data storage
- MariaDB — data storage
- NGINX — http requests
- matrix — online support / communication
Open Source Made by APIBAN
Videos
APIBAN - Fred Posner (CommCon 2021)
Using APIBAN to protect your phone system (in under 5 minutes)
APIBAN: Protecting you from unwanted SIP traffic (tadsummit 2021)