API keys are used to authenticate a caller triggering an HTTP or API Trigger that is using API Key authentication.  An API key is valid only for a specific Environment. API key access rights are determined by the Rulesets applied to it. 

Rulesets

Rulesets are used to group access rules used for API keys. Rulesets are shared across all Environments. This makes it possible to have a partner or a system have exactly the same access rights for multiple Environments, by having API keys for each environment share the same Rulesets. An API key can have multiple Rulesets active at once.

In the example above, System X hasaccess to the Development, Testing and Production Environment (using different keys). However, exactly the same access rules are applied since they all share the same Ruleset. This means that if everything works as expected in the Test environment, then we can be sure that a key with the same Rulesets will work in Production. 

Rules

A Ruleset consists of simple Rules which gives the user access to an URL path called with a specific method. Path parameters are not supported. 

Rules are enforced by the Agent receiving the HTTP(S) call to an HTTP or API trigger. The agent is aware of all API keys for the Environment it resides in, as well as which Rulesets are applied. For each Rule that is applied to the API key, the path of the call as well as the method used is inspected. If the path starts with the same path as in the Rule and the method matches, then the call goes through.

Example
 An agent is running on https://agent.org:9999. A call is made to https://agent.org.9999/api/myApi/v2/getStatus?paging=4

The part of the call that determines if the call gets access is /api/myApi/v2/getStatus, the rest is ignored. Let's say this call is made with GET.

A rule with the path /api/ and ANY method will allow this call to go through, since the path starts with the same and any method is allowed.

However, a rule configured to match /api/myApi/v1 will not go through, since the start of the paths does not match fully.

Note that the comparison between the rule path and the call path is case insensitive. 

Configuration

API Keys and Rulesets are managed in the Administration->API Keys page. 

Rulesets

Rulesets contain a collection of Rules. Each Rule has a path and a method. By clicking on the path, it's possible to see which API specifications are covered by the rule (or if a full API specification base path is covered, which operations in a specification is covered). *Note that operations containing path parameters are not shown in this list since they might or might not be covered by the rule. * 

A ruleset has list of API keys that are using it. New keys can easily be added or old keys removed from there. Whenever a Ruleset is changed, updates are sent to the Agents.

API Keys

API keys are created per Environment, and cannot be moved or copied to other. Once the environment has been set after creation it won't be possible to change it. Once the key has been saved, a key value will be generated for use. It's possible to add or remove Rulesets that should affect the API Key in the API Key page.  

Throttling

Agents and API gateways can do simple throttling on requests based on the API keys. If you set the "Request limit" for an API key, the agent (or API gateway) will check that the key is not used more than the given number of times within the time period. The first request with the API key will start a new time period. If there are more requests within the time period than the given limit, the extra calls will receive an HTTP 429 response. After the period has ended, a new time period will start again with the first call using a specific API key.

Please note that the limits are currently checked per Agent (or API gateway) instance. This means that in a load balanced environment, the effective limits will actually scale together with the number of agents. E.g. if the API key request limit is set to 100 per hour, and you have two agents in an agent group, the effective limit will be about 200 requests per second. It could also be a little less, depending on how evenly the load balancer shares the load: once one of the agents hits the request limit, it will start returning the HTTP 429 responses, even if the other agent might not yet have hit its limit.

Using API Keys from the Agent API Discovery page

Once the API keys and ruleset has been set up, and there's a process that's using API key authentication, the Agent API Discovery page will allow you to enter an API key. The API key is added as a header to the request (X-ApiKey).

Passing an API key from a client

An API Key can be passed in the request headers specified in API specification or in query parameters.

In version 5.3.3 and before API Key must be passed in either within the Authorization header using the ApiKey type or with the X-ApiKey

For example: Authorization: ApiKey 12345678-1234-1234-1234-1234567890ab or: X-ApiKey: 12345678-1234-1234-1234-1234567890ab

Did this answer your question?