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 refreshes edge server IP addresses for routine maintenance. With Firewall Rules Notification, you can manage who receives email notifications about the planned changes. Akamai provides two to five weeks of advance notice before activating the IP addresses.

It’s important that you update your company’s firewall to accept traffic from new IP addresses, or remove access to decommissioned ones. Keeping your firewall rules current ensures that requests served through the IPs listed in our CIDR blocks reach your origin.

The Firewall Rules Notification API lets you:

  • subscribe or unsubscribe users to notifications for specific services.
  • retrieve subscription and service information.
  • view CIDR block information required to update your firewall rules.

This API provides you with a programmatic interface to the same functionality available in Akamai Control Center.

Who should use this API

Use this API if you manage your company’s firewall. Programmatically retrieve Akamai CIDR block details to add or remove addresses in your firewall rules. You can also automate subscription settings that define who receives email notifications about upcoming changes to the CIDR blocks.

Getting started

Before using FRAPI for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Firewall Rules Notification, and set the access level to READ-WRITE.

Resources

The following lists unique concepts for this API:

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

  • CIDRs with a status of Deleted are still visible 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
Add or remove subscriptions PATCH /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 run the operation again.

GET /firewall-rules-manager/v1/services

Status 200 application/json

Object type: Service

Download schema: services.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 information about a specific service.

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

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

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

Status 200 application/json

Object type: Service

Download schema: service.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. 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

Object type: CidrBlock

Download schema: cidrBlocks.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 the subscription information for configurations you created yourself. If someone else subscribed you to a service, you won’t see that subscription returned by this operation.

GET /firewall-rules-manager/v1/subscriptions

Status 200 application/json

Object type: Subscription

Download schema: subscriptions.json

Response body:

{
    "subscriptions": [
        {
            "subscriptionId": 1,
            "serviceId": 13,
            "serviceName": "Test IPs",
            "createdBy": "username",
            "email": "mp@mail.com",
            "signupDate": "2017-03-28"
        },
        {
            "subscriptionId": 2,
            "serviceId": 15,
            "serviceName": "CCUAPI",
            "createdBy": "username2",
            "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

Object type: Subscription

Download schema: subscriptionPutRequests.json

Request body:

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

Status 200 application/json

Object type: Subscription

Download schema: subscriptions.json

Response body:

{
    "subscriptions": [
        {
            "subscriptionId": 1,
            "serviceId": 13,
            "serviceName": "Test IPs",
            "createdBy": "username",
            "email": "mp@mail.com",
            "signupDate": "2017-03-28"
        },
        {
            "subscriptionId": 2,
            "serviceId": 15,
            "serviceName": "CCUAPI",
            "createdBy": "username2",
            "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.

Add or remove subscriptions

Subscribe or unsubscribe users to services.

PATCH /firewall-rules-manager/v1/subscriptions

Content-Type: application/json

Object type: Subscription

Download schema: subscriptionPatchRequests.json

Request body:

{
    "subscriptions": [
        {
            "op": "add",
            "path": "/",
            "serviceId": 13,
            "email": "mp@mail.com"
        },
        {
            "op": "remove",
            "path": "/15"
        }
    ]
}

Status 200 application/json

Object type: Subscription

Download schema: subscriptions.json

Response body:

{
    "subscriptions": [
        {
            "subscriptionId": 1,
            "serviceId": 13,
            "serviceName": "Test IPs",
            "createdBy": "username",
            "email": "mp@mail.com",
            "signupDate": "2017-03-28"
        },
        {
            "subscriptionId": 2,
            "serviceId": 15,
            "serviceName": "CCUAPI",
            "createdBy": "username2",
            "email": "abcd@akamai.com",
            "signupDate": "2017-10-11"
        }
    ]
}
  1. Create a request object with an empty subscriptions array.

    If you want to add a set of subscriptions:

    1. Run List services and collect the serviceId value for the service you want to subscribe the users to.

    2. For each new subscription:

      1. Add an object to the subscriptions array.
      2. Specify the op member as add.
      3. Specify the path to the subscriptionId as a blank /.
      4. Specify the serviceId of the service you want to subscribe to.
      5. Specify the email address of the user you want to subscribe.

    If you want to remove a set of subscriptions:

    1. Run List subscriptions and collect the subscriptionId values you want to remove.

    2. For each subscription you want to remove:

    3. Add an object to the subscriptions array.

    4. Specify the op member as remove.

    5. Specify the path to as / followed by a subscriptionId you want to remove.

  2. PATCH the request object with added and removed subscriptions 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.

Subscription

Displays subscriptions for a service.

Download schema: subscription.json

Sample GET response:

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

Subscription members

Member Type Description
Subscription: Displays subscriptions for a service.
createdBy String A username who created a subscription.
email String The email of the user subscribed to a service and receiving notifications about the 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.
subscriptionId Integer A unique identifier for a subscription.

Service

Specifies service information.

Download schema: service.json

Sample GET response:

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

Service members

Member Type Description
Service: Specifies service information.
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 blocks 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 Description
CidrBlock: Describes CIDR blocks and the services they belong to.
changeDate String The ISO 8601 date when a 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 a 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. The date is typically two weeks after the CIDR block’s creation date.
lastAction Enumeration The last Action, or change, made to a 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.