Firewall Rules Notification API v1

Subscribe yourself and others to CIDR block changes and retrieve CIDR blocks to include in your firewall rules.

Learn more:


Overview

Akamai periodically updates edge server IP addresses for routine maintenance and, when that happens, it is important that you update your company’s firewall to accept traffic from new IP addresses, or remove access to your origin from IP addresses that were decommissioned.

The Firewall Rules Notification API lets you manage who receives notifications about changes Akamai makes to IP addresses. You can subscribe or unsubscribe users to notifications for specific services, retrieve subscription and service information, and get CIDR block information with which to update your firewall rules. This API provides you with a programmatic interface to the same functionality available in the Luna Portal.

Who should use this API

Use this API if you manage your company’s firewall and want to programmatically retrieve Akamai CIDR blocks so you can add or remove them from your company’s firewall. Additionally, use this API to automate adding or removing users from being notified about changes to the CIDR blocks.

Getting started

Before using FRAPI for the first time:

  • Review Get Started for API tools that Akamai provides.

  • See Authorize Your Client Using Identity Management to create your API access credentials and authorizations. As detailed in The API Identity Model, you then access the API using custom host names that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To access this API you need to have certain credentials. You assign credentials in the Manage APIs application in Luna Control Center.

    1. Log in to Luna at control.akamai.com.

    2. Navigate to the Manage APIs application.

    3. Create new credentials for yourself including the specific scope you need either READ-ONLY or READ-WRITE.

Resources

The following lists unique concepts for this API:

  • Activation date in the Luna application is the same thing as the effective date in the API.

  • CIDRs with a status of Deleted are still visible and returned in response objects. Deleted for this API means that CIDR block is no longer in use and no longer serves traffic to your origin. You can remove that CIDR block from your firewall rules.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List Services GET /firewall-rules-manager/v1/services
Get a Service GET /firewall-rules-manager/v1/services/{serviceId}
List CIDR Blocks GET /firewall-rules-manager/v1/cidr-blocks{?lastAction,effectiveDateGt}
List Subscriptions GET /firewall-rules-manager/v1/subscriptions
Update Subscriptions PUT /firewall-rules-manager/v1/subscriptions

List services

Get a list of services you are subscribed to. To see additional services, subscribe to them first and then run the operation again.

GET /firewall-rules-manager/v1/services

Status 200 application/json

Response Body:

[
    {
        "serviceId": 3,
        "serviceName": "TestIP",
        "description": "Test IPs"
    },
    {
        "serviceId": 4,
        "serviceName": "TestIP again",
        "description": "Test IPs"
    }
]
  1. Make a GET request to /firewall-rules-manager/v1/services.

  2. The response is an array of Service objects. Locate a serviceID and save it for later use.

Get a service

Get a specific service.

GET /firewall-rules-manager/v1/services/{serviceId}

Sample: /firewall-rules-manager/v1/services/3

Parameter Type Sample Description
URL parameters
serviceId Integer 3 A unique identifier for a service.

Status 200 application/json

Response Body:

{
    "serviceId": 3,
    "serviceName": "TestIP",
    "description": "Test IPs"
}
  1. Run List Services and choose a service from the array. Store the serviceId for later use.

  2. Make a GET request to /firewall-rules-manager/v1/services/{serviceId}.

  3. The response is a Service object

List CIDR blocks

List all CIDR blocks for all services you are subscribed to. To see additional CIDR blocks, subscribe yourself to more services and run this operation again.

GET /firewall-rules-manager/v1/cidr-blocks{?lastAction,effectiveDateGt}

Sample: /firewall-rules-manager/v1/cidr-blocks?lastAction=add&effectiveDateGt=2017-02-21

Parameter Type Sample Description
Optional query parameters
effectiveDateGt String 2017-02-21 The ISO 8601 date the CIDR block starts serving traffic to your origin. Please ensure your firewall rules are updated to allow this traffic to pass through before the effective date.
lastAction Enumeration add Whether a CIDR block was added, updated, or removed from service. You can use this parameter as a sorting mechanism and return only CIDR blocks with a change status of add, update, or delete. Note that a status of delete means the CIDR block is no longer in service, and you can remove it from your firewall rules.

Status 200 application/json

Response Body:

[
    {
        "cidrId": 13742,
        "serviceId": 9,
        "serviceName": "PERF_ANALYTICS",
        "cidr": "66.171.230.134",
        "cidrMask": "/32",
        "port": "80,443",
        "creationDate": "2017-02-21",
        "effectiveDate": "2017-02-21",
        "changeDate": "2017-02-21",
        "minIp": "66.171.230.134",
        "maxIp": "66.171.230.134",
        "lastAction": "add"
    }
]

List subscriptions

List subscriptions you created for yourself and other users. You can only see subscription information based on what you created yourself, so if someone else subscribed you to a service, you will not see that subscription returned by this operation.

GET /firewall-rules-manager/v1/subscriptions

Status 200 application/json

Response Body:

{
    "subscriptions": [
        {
            "serviceId": 13,
            "serviceName": "Test IPs",
            "email": "mp@mail.com",
            "signupDate": "2017-03-28"
        },
        {
            "serviceId": 15,
            "serviceName": "CCUAPI",
            "email": "abcd@akamai.com",
            "signupDate": "2017-10-11"
        }
    ]
}
  1. Make a GET request to /firewall-rules-manager/v1/subscriptions.

  2. The response is an array of Subscription objects.

Update subscriptions

Subscribe or unsubscribe users to services.

PUT /firewall-rules-manager/v1/subscriptions

Content-Type: application/json

Request Body:

{
    "subscriptions": [
        {
            "serviceId": 13,
            "email": "mp@mail.com"
        },
        {
            "serviceId": 15,
            "email": "abcd@akamai.com"
        }
    ]
}

Status 200 application/json

Response Body:

{
    "subscriptions": [
        {
            "serviceId": 13,
            "serviceName": "Test IPs",
            "email": "mp@mail.com",
            "signupDate": "2017-03-28"
        },
        {
            "serviceId": 15,
            "serviceName": "CCUAPI",
            "email": "abcd@akamai.com",
            "signupDate": "2017-10-11"
        }
    ]
}
  1. Run List Subscriptions.

  2. The response is an array of Subscription objects. Modify the array of objects.

  3. PUT the modified object back to /firewall-rules-manager/v1/subscriptions.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether its value is empty or null.

Subscription

Displays subscriptions for a service.

Download schema: subscription.json

Sample GET response:

{
    "subscriptions": [
        {
            "serviceId": 13,
            "serviceName": "Test IPs",
            "email": "mp@mail.com",
            "signupDate": "2017-03-28"
        },
        {
            "serviceId": 15,
            "serviceName": "CCUAPI",
            "email": "abcd@akamai.com",
            "signupDate": "2017-10-11"
        }
    ]
}

Subscription members

Member Type Required Description
email String One or more emails belonging to people subscribing to a service. These email addresses receive the notifications for CIDR block updates.
serviceId Integer A unique identifier for a service.
serviceName String The name of a service. This is often the same as the product you purchased.
signupDate String The date a subscriber signed up for notifications. The date is in ISO format.

Service

Specifies service information.

Download schema: service.json

Sample GET response:

{
    "serviceId": 3,
    "serviceName": "TestIP",
    "description": "Test IPs"
}

Service members

Member Type Required Description
description String A description of the service.
serviceId Integer A unique identifier for a service.
serviceName String The name of a service. This is often the same as the product you purchased.

CidrBlock

Describes CIDR block and the services they belong to.

Download schema: cidrBlock.json

Sample GET response:

[
    {
        "cidrId": 13742,
        "serviceId": 9,
        "serviceName": "PERF_ANALYTICS",
        "cidr": "66.171.230.134",
        "cidrMask": "/32",
        "port": "80,443",
        "creationDate": "2017-02-21",
        "effectiveDate": "2017-02-21",
        "changeDate": "2017-02-21",
        "minIp": "66.171.230.134",
        "maxIp": "66.171.230.134",
        "lastAction": "add"
    }
]

CidrBlock members

Member Type Required Description
changeDate String The ISO 8601 date when the CIDR block was last updated.
cidr String A list of IP addresses belonging to Akamai edge servers for a particular service.
cidrId Integer A unique identifier for a CIDR block.
cidrMask Enumeration Indicates the range (start and end IP) of the CIDR block. /32 and /64 denote whether the IP addresses in the CIDR block are IPv4 or IPv6, respectively.
creationDate String The ISO 8601 date the CIDR block was created.
effectiveDate String The ISO 8601 date the IP addresses start passing traffic. Make sure your firewall rules are updated to accept traffic before this date. This date is typically two weeks after the CIDR block’s creation date.
lastAction Enumeration The last Action, or change, made to the CIDR block. Either add, update, or delete.
maxIp String The maximum IP is the top of the range for the CIDR block.
minIp String The minimum IP is the base of the range for the CIDR block.
port String The set of comma-delimited ports through which your server receives traffic from Akamai servers.
serviceId Integer A unique identifier for a service.
serviceName String The name of a service. This is often the same as the product you purchased.

Errors

This section tells you about the Firewall Rules Notification API’s error response format, and details the range of HTTP status codes the API produces.

Error Responses

The Identity Management API responds with HTTP Problem error objects that provide details useful for debugging.

The following shows a typical error response. The outer object characterizes the overall problem, while the details array lists potentially more than one problem detected in the request.

{
  "type" : "/firewall-rules-manager/error-types/5",
  "status" : 404,
  "title" : "ServiceId doesn't exist",
  "detail" : "ServiceId: 233 not found",
  "instance" : "",
  "errors" : [ ]
}

HTTP status codes

This section lists the range of HTTP response codes the API may produce for both success and error cases:

Code Description
200 Request OK.
302 The requested item is temporarily available at the link provided.
400 Bad Request.
401 Authentication failure.
403 Access Denied.
404 Resource not found.
405 Method not supported.
415 Unsupported media type.
500 Internal server error.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable.

Last modified: 6/1/2017