APIBAN

Block/Identify Traffic

APIBAN is a FREE service thanks to our generous sponsors.

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).

The API

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.

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.

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 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:

Example

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:

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

Example

curl https://apiban.org/api/get
	-X POST
	-H 'Authorization: Bearer 123456789101112abcdefg'
	-H 'Content-Type: application/json'
	-d '{"set":"all", "id":"7894354"}'

Example Responses

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

Example

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"}'

Example Responses

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.

Did you know the FREE APIBAN iptables client now supports ipset?

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.

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

Example

curl https://apiban.org/ipset/123456789101112abcdefg/list

Example Responses

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

Example

curl https://apiban.org/ipset/123456789101112abcdefg/listall

Example Responses

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: set

Example

curl https://apiban.org/ipset/123456789101112abcdefg/cisco

Example Responses

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: set

Example

curl https://apiban.org/ipset/123456789101112abcdefg/juniper

Example Responses

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 the generosity of our sponsors.

We would also like to thank Ivan Nyarko and our github 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.

• Matrix (best method): #apiban:matrix.lod.com
• LOD: https://lod.com

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/s requests
• matrix — online support / communication

Open Source Made by APIBAN

• apiban-client-nftables (nftables client)
• apiban-client-go (iptables/ipset client)
• nftables-api (local api for nftables)
• apiban-client-bash
• APIBAN-tools (go lib)

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)

Kamailio World 2026: APIBAN and Kamailio