SaaS IP/Geo Access API

The SaaS IP/Geo Access API allows you to set up whitelists and blacklists based on IP address/CIDR lists as well as geographic location.

NOTE: This API is currently in beta.

Who Should Use this API

Developers who want to set up access rules for a SaaS application that are based on either IP address/CIDR list or geography.

Concepts

When using this API, you should be familiar with the following concepts

About Group IDs and Contract IDs

When using this API, your level of access depends on the groups and contracts your Luna Control Center username is associated with. If your username is not associated with the group ID and contract ID you selected, then the request will fail.

To understand contracts and groups, you need to understand how accounts work at Akamai. Akamai customers access all their services via an account key. While administrators (customers who administer their own accounts) may have access to more than one account, they generally provision all their web assets under a single account. Within an account, there are contracts and groups:

  • contracts: Each account features one or more contracts, each of which has a fixed term of service during which specified Akamai products and optional modules are active.

  • groups: Each account features a hierarchy of groups that control access to properties and help consolidate reporting functions. Customers typically set up groups to match their firm’s organizational hierarchy.

When using any of the GET or POST operations available for this API, you must include the group ID (groupId) and contract ID (contractId) in the query parameter.

Rules and Policies

With this API, you can design rules to either allow or deny access to a SaaS application. A rule defines which requests to allow or deny based on IP address/CIDR lists and/or geographic location.

Your rules define a policy. You can have different versions of a policy. When you activate SaaS IP/Geo Access rule(s), you activate a specific policy version.

Endpoints

This API includes the following endpoints:

  • The policies endpoint enables a customer to create a policy and the rules associated with that policy.

  • The activations endpoint allows you to activate your SaaS IP/Geo Access policy on the Akamai network you select.

Prerequisites

Before working with this API, you should complete the following prerequisites:

  • OPEN Prerequisites: read all the sections and complete any tasks listed in the Getting Started section of the Introduction.

  • API Access: Before you can access this API, the SaaS Provider Option needs to be added to your contract.

  • Contract IDs and Group IDs: Prior to working with this API, you need to determine which contract IDs and group IDs to use. You can use the Property Manager API, to locate the IDs you need.

Input/Output Formats

Request Input (POST/PUT Body Content)

Various calls may require you to use query arguments or form elements to pass additional content to the API.

For this API, POST operations must be in the application/x-www-form-urlencoded content type format.

In addition, the contract ID (contractId) and group ID (groupId) may need to be passed in as query parameters.

Response Output

This API uses the JavaScript Object Notation (JSON) response format.

For some operations, a specific status code is returned in the response.

Status Codes Description

For this API, the following status codes may be returned with a response.

Code Description
200 OK
202 Accepted. The submission was accepted and will be processed accordingly.
400 Bad Request. Please provide all the required parameters.
403 User is not authenticated.
404 The requested resource is not found.
409 Conflict.
500 There is a problem processing your request. Please try again later. The details of this error are provided in the response body.

Operations

Action Operation API Endpoint
Create a policy. POST /config-saas-rules/v2/policies{?cloneId}{?contractId}{?groupId}
Get information for all policies. GET /config-saas-rules/v2/policyInfoMaps{?contractId}{?groupId}
Get details for a single policy. GET /config-saas-rules/v2/policies/{id}
Update a policy. PUT /config-saas-rules/v2/policies/{id}
List policy version information. GET /config-saas-rules/v2/policyInfoList/{policyId}
Activate a policy. PUT /config-saas-rules/v2/activations/{?network}{?ids}
List policy activations. GET /config-saas-rules/v2/activations{?historyOnly}

Policy JSON Document Considerations

The Policy JSON document contains your rules. For this API, all JSON documents sent to the server use

  • application/x-www-form-urlencoded as the content type, and

  • this format: query=<url-encoded JSON document>, where the query= portion is not URL encoded.

For example, the actual POST data for getAllPolicyInfoMaps will look something like this:

query=%7B%22policyManagerRequest%22%3A%7B%22command%22%3A%22getPolicyInfoMapUsingACGIDs%22%2C%22getPolicyInfoMapUsingACGIDs%22%3A%7B%7D%7D%7D

Content-Length Header for POST Requests

You need to set the Content-Length header for all POST requests to the server.

Data Members

This section provides information on the members included in the requests or responses.

Policy Members

The Policy object features the following members.

NOTE: Members returned in responses that are not listed in the table below are for Akamai internal use.

Member Type Description
id Number The unique ID that corresponds to a specific policy.
policyId Number An ID that is associated with all versions of a policy.
createdBy String The name of the user who created this specific policy.
createDate Number The date this specific policy was created (in milliseconds since epoch).
version Number The specific version of this policy.
activatedProduction Number If true, this policy is activated in the production network.
activatedStaging Number If true, this policy is activated in the staging network.
activatedTest Number If true, this policy is activated in the test/QA network.
description String The description of this specific policy.
policyName String The name used for every version of this policy. Valid characters include: a-z, A-Z 0–9 % - _ . ! ~ * " ( ) : @ & = + $ , ’.
policyDescription String The default description for every version of the policy.
policyCreatedBy String The user who created the initial policy.
policyLastModifiedBy String The user who last modified the policy.
policyCreateDate Number The date the initial policy was created (in milliseconds since epoch).
policyLastModifiedDate Number The date the initial policy was modified (in milliseconds since epoch).
matchRules Array A JSON structure that defines the rules for this policy. This property is not assigned by Akamai.

matchRules Members

The matchRules member contains all of your SaaS Access rules. For this API, the valid match rules are for IP address/CIDR list or geographical location. For example:

  • You want to either allow or deny requests from country X.
  • You want to either allow or deny requests from IP specific addresses.

A matchRules member includes the members in the following table.

NOTE: Members returned in responses that are not listed in the table below are for Akamai internal use.

Member Type Description
type String The type of rule. For this API, use this string: saMatchRule.
start Number The start time (in milliseconds since epoch) for the period in which this match will be valid.
end Number The end time (in milliseconds since epoch) for the period in which this match will be valid.
matches Array See matches below.
name String The name of the rule.

Matches Members

Each object in the matches member defines potential conditions (like case sensitivity). If all of the conditions you set are true, then the Edge Server will forward the request on to the origin.

A matches member contains an array of objects with the following members/conditions:

Member Type Description
caseSensitive Boolean If true, the match is case sensitive.
matchOperator Enumeration You must set this member to contains.
matchType Enumeration The type of match used. Possible values include: clientip and countrycode.
matchValue String This value depends on the matchType. See the matchValue Examples section below for details.
negate Boolean If true, negates the match.

matchValue Member Examples

The matchValue members provide information about the match types used for access control. The following are the valid match types for this API.

Member Description Example
clientip A list of space-separated IP addresses and/or CIDR blocks to match on. 10.0.5.0/24 192.168.0.1 192.168.0.2
countrycode The country to match on. Available values are listed in the Luna Portal. US

Activation Members

The Activation object has the members listed in the table below.

NOTE: Members returned in responses that are not listed in the table below are for Akamai internal use.

Member Type Description
productionStatus String Denotes whether or not the policy is activated on Akamai’s production network.
productionLastUpdated Number The date the policy was last updated on Akamai’s production network.
stageLastUpdated Number The date the policy was last updated on Akamai’s staging network.
stagingStatus String Denotes whether or not the policy is activated on Akamai’s staging network.
propertyName String The name of the property associated with this policy.
versions Array Existing versions of the policy that have been saved to the database.
activatedPolicyVersions Array The policy versions that have been activated.

Last modified: 12/6/2016