Skip to main content

IP Whitelist

Overview​

An IP Whitelist is a security feature that restricts access to a system or application based on a list of trusted IP addresses. Only requests originating from the specified IPs are allowed to access the protected resource. This feature is commonly used to add another layer of security by allowing only known or trusted IP addresses to access certain functionalities or services within an application.

In Amani Studio, if no IP whitelist is configured for a company, all IP addresses will have access to the Studio.

There are three primary endpoints that allow users to:

  • GET a list of all whitelisted IPs
  • POST (add) a new IP to the whitelist
  • DELETE an IP from the whitelist by ID

API Endpoints​

1. Get All Whitelisted IPs​

This endpoint retrieves a list of all the IP addresses that are currently whitelisted.

  • Endpoint: GET /api/v2/ip-whitelist

    • Request: 
      curl -X 'GET' \
        '<base_url>/api/v2/ip-whitelist' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer <user_token>'

  • Response:

    • 200 OK – A list of all whitelisted IP addresses.
    • 401 Unauthorized – Incorrect authentication credentials.
    • 403 Forbidden – You do not have permission to perform this action. 
      [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "company_name": "Test",
          "address": "31.223.84.238/32"
        }
      ]

2. Add a New IP to the Whitelist​

This endpoint adds a new IP address to the whitelist. The IP can be provided in CIDR notation or as a plain IP address (without CIDR).

  • Endpoint: POST /api/v2/ip-whitelist

  • Request:

    curl -X 'POST' \
      '<base_url>/api/v2/ip-whitelist' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <user_token>' \
      -d '{
      "address": "127.0.0.1/32"
    }'

  • Request Body:

    • address: The IP address to whitelist. Can be in CIDR notation (e.g., "127.0.0.1/32") or just an IP without CIDR (e.g., "127.0.0.1").

  • Response:

    • 201 Created – The new IP address is successfully added to the whitelist.
    • 400 Bad Request – A valid 'field_name' is required.
    • 401 Unauthorized – Incorrect authentication credentials.
    • 403 Forbidden – You do not have permission to perform this action. 
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "company_name": "Test",
        "address": "127.0.0.1/32"
      }

3. Delete an IP from the Whitelist​

This endpoint deletes an IP address from the whitelist based on the provided ID.

  • Endpoint: DELETE /api/v2/ip-whitelist/{id}

  • Request:

    curl -X 'DELETE' \
      '<base_url>/api/v2/ip-whitelist/{id}' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer <user_token>'

  • Path Parameter:

    • id: The unique identifier of the IP address to delete.

  • Response:

    • 204 No Content – The IP address was successfully removed from the whitelist.
    • 400 Bad Request – This request is invalid
    • 401 Unauthorized – Incorrect authentication credentials.
    • 403 Forbidden – You do not have permission to perform this action.
    • 404 Not Found – The specified IP address does not exist in the whitelist.