Usage

Endpoint for greylist checking-adding-removing

Endpoints related to adding-removing-checking a greylisted address.

  • POST api.bitninja.io/api/addIpToGreylist
  • POST api.bitninja.io/api/deleteIpToGreylist
  • POST api.bitninja.io/api/checkIpOnGreylist

Common details shared between ALL endpoints

They all require a JWT token for authorization. This will require the license key you can see at https://admin.bitninja.io/main

If we include a “result_mode=json” GET parameter, the result will be in json, that will look like this:

{ result: string }

PHP status code does NOT change even if validation fails or the action fails. It will always return 200.

Before every action carried out, the API will check if it is indeed a PUBLIC valid IPV4 address or not.

The limits are as follows:

  • Greylist additions/day: 6000.
  • Greylist removals /day: 1000.

Note

The API will NOT forward the request if the IP is on our global whitelist (e.g. BitNinja’s API IP addresses)

Common responses among all endpoints

If the IP is invalid:

{result: "[1.2.3.4] is invalid"}

If the IP is private:

{result: "[1.2.3.4] is private"}

If you exceed a limit:

{result: "Sorry, but you have reached the maximum limit"}

Greylist operations

Checking

POST api.bitninja.io/api/checkIpOnGreylist?result_mode=json (POST Parameters: IP)

Example Responses

If the IP is NOT greylisted:

{"result": "[1.2.3.4] is currently not on global greylist"}

If the IP is on user-level greylist:

{"result": "[1.2.3.4] is currently on your personal greylist"}

If it is greylisted:

{"result": "[1.2.3.4] is on global greylist"}

Example CURL request

curl --location --request POST 'https://api.bitninja.io/api/checkIpOnGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>' --form 'ip="1.2.3.4"'

Adding

POST api.bitninja.io/api/addIpToGreylist?result_mode=json (POST Parameters: IP)

Example Responses

If the IP is already on user-level greylist:

{"result": "[1.2.3.4] is already on your greylist"}

If the IP is on global greylist:

{"result": "[1.2.3.4] is already on global greylist"}

If the IP was successfully added to the greylist:

{"result": "[1.2.3.4] has been added to greylist"}

Example CURL request

curl --location --request POST 'https://api.bitninja.io/api/addIpToGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>' --form 'ip="1.2.3.4"'

Removing

POST api.bitninja.io/api/deleteIpFromGreylist?result_mode=json (POST Parameters: IP)

Example Responses

If the IP is not on greylist:

{"result": "[1.2.3.4] is not on greylist"}

If the IP has been successfully removed:

{"result": "[1.2.3.4] has been removed from greylist"}

Example CURL request

curl --location --request POST 'https://api.bitninja.io/api/deleteIpFromGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>'  --form 'ip="1.2.3.4"'