The OPEN Platform

The Open Platform (EdgeGrid) introduces a consistent, secure, high-performance, and scalable API interface for developers to programmatically interact directly with the Akamai Intelligent Platform™. This document introduces the fundamental OPEN API identity model and provides an overview of platform services, service APIs, API clients, and the OPEN authentication and authorization protocol.

The Open Platform exposes the Akamai Intelligent Platform™ as a set of services. Each service then implements one or more APIs. When a client application invokes an API via the Open Platform, that client operates as an agent for the user identity configured in the Akamai Luna Control Center API Client authorization. From the perspective of the Akamai Intelligent Platform™, the API client is the Luna Control Center user.

API Clients are provisioned and maintained by Akamai customers (via administrative users) in Luna Control Center. In Luna Control Center tools, API clients are stored in client collections organized by service.

Client Credentials

New API clients are issued two security parameters called client credentials. The first credential is the client token. While the API client name identifies the client to an administrative user, the client token identifies the client to both the developer’s software application and the Akamai Platform. Paired with the client token, the second credential is called the client secret. Together, the client credentials are used for authentication when an API call is made. Client credentials are designed to be rotated. Akamai recommends that customers adopt a rotation schedule that is in line with their security policies.

Client Authorization

Authentication to the Open Platform alone does not entitle the client application to interact with the APIs. The API clients must also be granted access to APIs through a client authorization. During API invocation the API client is matched to a client authorization by submitting another security parameter called the access token. The access token and the base URL are used to verify that a particular API client (identified by its client credentials) is entitled to interact with the specified API.

Like other strong API security schemes, Akamai requires that during API invocation, the HTTP request message is digitally signed using the client secret. The developer’s software application must implement the client authentication protocol (detailed below). OPEN provides reference implementation and utilities in the form of libraries to make API invocation simple. See Akamai OPEN on GitHub to download the Akamai supported implementations.

Open API URLs Explained

As mentioned during the introduction of the security parameters above (client token, client secret, and access token), Luna Control Center also issues a unique base URL specific to each client collection. All API clients from the same client collection share the same base URL. Here is an example of a base URL including a specific API endpoint in the first path element.

 https://akzz-vesvjee7gbimrryr-oganfff5qiat27gb.luna.akamaiapis.net/diagnostic-tools/...

The base URL is composed of four components, the first being the Akamai Open Platform domain.

 akamaiapis.net

Open services appear next in the URL. Each service is represented as a subdomain. For example, all Luna Control Center APIs use the Luna service.

 luna.akamaiapis.net

The fourth (left-most) label in the hostname

 akzz-vesvjee7gbimrryr-oganfff5qiat27gb

identifies the unique client collection used to group clients in Luna Control Center. Client developers should treat this label as an opaque token.

NOTE: Sometimes the hostname in the base URL is referred to as the service consumer domain, and the subdomain representing the Platform Service is referred to as the service provider. From an identity architecture perspective, the developer may understand API Clients as being the principal of the API request, authorized by a resource owner (in a separate workflow/protocol) who is represented by the service consumer during message exchange with the service provider. In Luna Control Center, the administrative user granting access to a client acts as the resource owner.

URL Path

The first path element of the URL such as

/diagnostic-tools/

represents a specific API exposed via the service. The remaining path elements in the URL represent the resource model of the API. The resource model for each API is documented in the reference documentation and related learning material here.

Akamai refers to the API name (the first path element of the URL) as the service provider endpoint.

Relationship between Client Collections and Account Groups in Luna Control Center

Normally an Akamai customer has one Account; however, in Luna Control Center, authenticated users may have access to one or more accounts. Within an account, customers may optionally configure groups in a hierarchy. Some customers use groups to isolate users and/or configuration assets. The account, user, group identity architecture has evolved over many years. To ensure that the OPEN API architecture is sufficiently decoupled from the Luna Control Center tools, Akamai has introduced the API client and client collections so that platform services can use a service oriented identity model.

Most customers will leverage OPEN APIs through one or a few client collections perhaps spanning one or a few account groups. Some larger, long-standing Akamai customers may have many client collections spanning dozens (and in a few cases hundreds) of account groups.

Relationship between Client Authorizations and Account Users in Luna Control Center

The first set of OPEN APIs are all from the Luna service. The preexisting Luna service APIs adapted for OPEN had been designed to require a Luna Control Center user as the principal of the request message. For these APIs, a complete client authorization process requires the administrative user to select a Luna Control Center user from the same account group as the client collection represents. In this way, pre-existing Luna service APIs are adapted for OPEN. In the future, new Luna service APIs as well as APIs from brand new Akamai services will complete client authorization processes in other ways. For example, a client authorization process may be associated with a different dimension of the Akamai Platform such as Digital Properties, SSL Certificates or even Appliances.