Akamai API Gateway

Start Your Free Trial
API Gateway

General FAQs

Q: Is API Gateway compatible with all types of API calls (SOAP, XML, JSON)?
A: API Gateway is compatible with RESTful APIs that use JSON and XML data formats


Q: What content types does API Gateway support?
A: For the most part, API Gateway is agnostic with regard to content type. 


Q: How do I interact with API Gateway?
A: A technical user may utilize the Luna GUI or the Akamai APIs to interact with API Gateway. 




Q: What is an API Key?
A: An API key is a randomly-generated alphanumeric string that an API client includes with an HTTP request to uniquely identify a calling client to the API. Keys provide authentication without authorization, as keys do not carry data. When using API Keys, Akamai recommends that all traffic be protected with HTTPS for productive usage.


Q: Where can an API key be located in a request? 
A: API keys are supported in request headers or in query string arguments.


Q: Do I need to upload keys to get started?
A: No, you can create brand new key collections on the Akamai Intelligent Platform.


Q: How do I upload API keys?
A: You may upload keys via the Luna Control Center or via API. Navigate to Configure > Manage Keys and Quotas. You may also upload keys via API call as documented here.


Q: Do you have any restrictions on the format of an API key?
A: Yes. The key must be no longer than 64 characters.


Q: How do I view the details of a key?
A: Clicking on the hyperlink of an individual key will bring up the details about the key itself. Each API key contains the following detail: 

  • Key ID: Akamai system-defined numeric value

  • Key value: String value specified within an HTTP request, used to "unlock" the API

  • Key label: String value, ideally a plain-language label

  • Tags: User-defined tool to help categorize keys into groups

  • Description field: Optional additional notes about a key

  • Timestamp: key creation date/time


Q: What formats does Akamai support for uploading existing keys?
A: If you wish to upload existing keys to Akamai, we support upload in XML, JSON, and CSV formats. 

XML files shall be formatted like this: 

<?xml version="1.0" encoding="UTF-8"?>
      <value>Key value</value>
      <label>Key label</label>       
      <tags>Key Tags;Delimited By;Tag3</tags>

JSON files shall be formatted like this: 


CSV files shall be formatted like this: 



Q: Where is the API documentation for API key management?
A: The API documentation can be found here.


Q: Where is the main documentation on API keys?
A: This documentation can be found in the User Guide.


Q: Are there any restrictions on the number of API keys?
A: There are no restrictions on the total number of keys, but API keys are allocated in groups of 10K.


Q: What is a key collection?
A: Keys are contained in groupings known as key collections. Keys in a key collection can be used to authenticate specific endpoints and resources, and to set quotas. Quota rate is set at the key collection level, rather than for a specific key. Note that a key collection may be comprised of a single key, if necessary.


Q: Do I have to assign a quota to a key? 
A: No, keys do not explicitly need quotas. Quotas are assigned to a key collection, and the number of hits defined by the quota is shared among all keys in that collection. 


Q: How long does it take to push a new key collection out to the network?
A: It takes 2-4 minutes to push a key collection out to the network. 


Q: Can I delete a key from a key collection?
A: Keys may be revoked individually or in batches from a given key collection. 


Q: Can I move a key between key collections?
A: Yes. Keys may be moved - either individually or in batches - from one key collection to another.


Q: Can I use JSON web Tokens and keys together? 
A: You may use them together, but we do not often see customers needing both. Using more than one identifier may also have a negative performance impact.


Q: If I revoke a key, is it revoked forever?
A: Revoking a key will keep it present in your collection for 120 days in a revoked state. If it has not been reinstated after 120 days, it is permanently deleted. 


Q: Do I need separate keys for staging and production?
A: You do not need separate keys for staging and production. The quota counters that apply to keys are also not kept separate on our staging and production networks; it is one common, shared quota. 


Q: How are API keys secured within the Akamai Platform?
A: Keys are stored salted and hashed in the Akamai platform for security.



JSON Web Tokens FAQs

Q: What is the difference between OAuth and JWT?
A: Auth2 is a framework for letting users and applications authorize specific permissions to other applications in both private and public settings. OAuth2 and JSON Web Tokens (JWT) are not alike, but also not incompatible. It is possible to have an OAuth2 implementation that issues JSON Web Tokens as an authentication mechanism.


Q: What cryptographic algorithms does JWT validation support for signature verification?
A: JWT validation will only support RSASSA-PKCS1-v1_5 using SHA-256. This algorithm is represented by the RSA256 value in the alg parameter of the JOSE header. See RFC-7518 for more information.


Q: Do you support HMAC for JSON Web Tokens?
A: We made a decision not to support HMAC signing of web tokens due to its inherently insecure nature that requires the use of shared secrets.


Q: Do I need to select all fields for validating a JWT?
A: No. You may select whatever fields you require for validation purposes.


Q: Is Akamai issuing JWT tokens?
A: No. You will need to have an IdP at origin or in your application that issues the token or generate the token inside an application. Akamai does not issue JWT tokens.


Q: What response is sent on a failed JWT validation?
A: An API client will receive an HTTP 403 error in response to a failed validation.


Q: Do I need to have a primary AND a backup RSA key for JWT validation?
A: The only requirement is to have a primary key, but we strongly encourage the use of a backup key to assist with key rotation. We support two public keys.


Q: Where in an HTTP request can my JWT exist?
A: API Gateway supports tokens in HTTP request headers, cookie, or query string arguments. You may customize the name of the header or query string argument that will contain the JWT. When delivering JWTs in query string arguments, it is important to ensure that the query string argument is not included in the cache key.

Q: How can I decompose a JWT?
A: Use the debugging tool provided by JWT.io


Q: Does Akamai strip the JWT from a request when that request is sent to origin?
A: Akamai will forward the JWT to origin for any additional work origin wishes to perform on the token.


Q: If Akamai is performing JWT validation at the edge, do I need to continue to perform JWT validation at origin?
A: Security best practices focus on "defense in depth," meaning that you should continue to validate tokens at origin as a secondary level of protection.


Q: In what field of a log file line can I see JWT actions taken?
A: The MKV field of an r line will contain JWT data under the "jwt" namespace.


Q: Can I set JWT validation at the resource level, or only at the endpoint level?
A:  You can define a JWT policy at the endpoint level, and exempt specific resources from requiring token validation.


Q: How do I generate an RSA keypair to use with JWT validation?
A: From the command line, use the following commands: 

$ ssh-keygen -t rsa -b 4096 -f jwtRS256.key 
$ openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub



Swagger/RAML FAQs

Q: How are the Open API Specification (OAS, formerly Swagger) and RESTful API modeling language (RAML) different?
A: The "ML" in RAML stands for "modeling language". This means RAML has as its design goal the ability to model API specifications, whereas Swagger is a means to describe an API.


Q: Is Swagger the same thing as the Open API Specification (OAS)?
A: In November 2015 SmartBear, the company that maintained the Swagger specification and associated tools, announced that it was helping create a new organization, under the sponsorship of the Linux Foundation, called the Open API Initiative. A variety of large technology companies (including Google, IBM, and Microsoft) were founding members. SmartBear donated the Swagger specification to the new group. On January 1st, 2016, the Swagger specification was renamed the OpenAPI Specification.


Q: Is Open API somehow related to Akamai’s {OPEN} APIs?
A: OAS is in no way connected to Akamai’s similarly-named {OPEN} API initiative. The naming overlap is purely coincidental.


Q: How can I import a Swagger file to Akamai?
A: You can upload a file manually or point Akamai to an unprotected URL hosting the file.


Q: Does API Gateway support import of API Blueprint files?
A: API Gateway does not support import of Apiary’s API Blueprint format files. The industry has moved to support of Swagger files almost exclusively.


Q: Which version of OAS/Swagger do you support?
A: We support Swagger version 2.0, with plans to add support for 3.0 in late 2018.


Q: Which version of RAML do you support?
A: We support RAML version 0.8.



User Quota FAQs

Q: Is quota the same as rate limiting?
A: No. Rate-limiting is used to protect infrastructure and generally focuses on measuring requests per second or per minute to an API. Quota is often conflated with rate-limiting, but quota focuses on enforcing a business service-level agreement, allowing a certain number of requests for a class of API customer. This is often the case where clients of a subscription-based API are granted a certain amount of requests per unit of time.


Q: Can I control when quota resets?
A: No. Quota at Akamai is a fixed (not rolling) window with defined reset times.


Q: What are the defined quota windows?
A: The defined quota windows are: 1 hour, 6 hours, 12 hours, 24 hours, per week, per month.


Q: What are quota response headers?
A: You may turn on the following quota-focused response headers that will be returned with every request: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Next. These headers help inform a client of the quota status to enable decision-making on request pacing.


Q: How do I manage quota settings?
A: Quota is tied to API keys, and is enabled inside the key management interface (Configure > Manage Keys and Quotas > Quota Settings)


Q: Does quota only work for a geographic region?
A: Quota works on a global basis, and typically denies an out-of-quota request in three seconds or less regardless of where in the world an API client is located.


Q: Can I use a token as an identifier for quota?
A: No. Only API keys can currently be used as identifiers for quota today.