API keys are utilized to authenticate a caller who triggers an HTTP or API Trigger utilizing API Key authentication. Each API key is only valid for a specific Environment and the access rights for an API key are determined by the Rulesets applied to it. 

Rulesets are utilized to group access rules for API keys, and they are shared across all Environments. This allows a partner or a system to have identical access rights for multiple Environments by sharing API keys across those environments that have the same Rulesets. An API key can have multiple active Rulesets simultaneously.
​

In the example above, System X has access 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. 

A Ruleset is comprised of simple rules that grant the user access to a specific URL path when called with a particular method. Path parameters are not supported in the Ruleset.

The Agent, which receives the HTTP(S) call to an HTTP or API Trigger, enforces the rules. The Agent is aware of all API keys for the Environment it operates in and the applied Rulesets. For every Rule that applies to an API key, the Agent examines the path of the call and the method used. If the path starts with the same path as the Rule, and the method matches, the call passes through.

Example
Suppose an Agent is operating on https://agent.org:9999, and a call is made to https://agent.org.9999/api/myApi/v2/getStatus?paging=4
​

The part of the call that determines access is /api/myApi/v2/getStatus, and the rest is ignored.

Let's assume this call is made with the GET method.

If a rule is set with the path /api/ and the method ANY, the call can go through since the path starts with the same string, and any method is allowed. However, if a rule is configured to match /api/myApi/v1, the call will not go through since the beginning of the paths does not match entirely.

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

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

Rulesets consist of a collection of Rules, each with a path and a method. By clicking on the path, it's possible to view the API specifications covered by the rule. If a full API specification base path is covered, the list displays the operations covered in the specification.

Note that the list does not include operations that contain path parameters since these might or might not be covered by the rule.

A ruleset has a list of API keys using it, and new keys can be easily added or old keys removed. Whenever a Ruleset is modified, updates are dispatched to the Agents.

API keys are created for each Environment and cannot be transferred or duplicated to others. Once an Environment has been specified during the creation of a key, it can't be modified afterward. After saving the key, a value will be generated for its use. In the API Key page, it's possible to add or remove Rulesets that should affect the API Key.

Agents and API gateways are capable of performing simple throttling on requests based on API keys. If the "Request limit" is configured for an API key, the agent (or API gateway) will verify that the key isn't used more than the specified number of times within the defined time period. A new time period will start with the first request using a specific API key. If there are more requests during the time period than the specified limit, the additional calls will receive an HTTP 429 response.

Please note that the limits are currently checked per instance of the Agent (or API gateway). This means that in a load-balanced Environment, the effective limits will scale according to the number of Agents. For example, if the API key request limit is set to 100 per hour, and there are two Agents in an Agent Group, the effective limit will be about 200 requests per second. The effective limit could also be slightly lower, depending on how evenly the load balancer shares the load. Once one of the Agents reaches the request limit, it will start returning HTTP 429 responses, even if the other Agent hasn't hit its limit yet.

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).
​

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

In version 5.3.3 and earlier, the API key had to be passed either within the Authorization header using the ApiKey type or with the X-ApiKey header.

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