Protecting an API with keys and rate limits in Boomi Cloud API Management
How to identify each API consumer, limit their traffic with throttles and quotas, and set it all up with packages, plans and keys in Boomi Cloud API Management.
Your API works, and the first partner wants access. Then a second one. Before the third arrives, you need answers to three questions: who is calling, how much are they allowed to call, and what happens when they call too much. This article explains the pattern behind those answers, then sets it up in Boomi Cloud API Management.
The pattern: identify, then limit
Identify every consumer
Each consuming application gets its own API key. Not one per company, and certainly not one shared by everybody: one per application and per environment. That gives you three things:
- you can see who generates which traffic,
- you can give different consumers different limits,
- you can revoke one consumer without affecting the others.
An API key identifies an application, not a user. If your API returns data that belongs to individual users, you also need OAuth 2.0 so that the call is made on behalf of a specific user. For system-to-system integrations, which is most B2B traffic, a key plus transport security is usually enough.
Limit with throttles and quotas
Two different limits solve two different problems:
| Limit | Example | Protects against |
|---|---|---|
| Throttle | 5 calls per second | Bursts that overload the backend (a runaway loop) |
| Quota | 20,000 calls a day | Total volume beyond what was agreed or paid for |
Use both. A consumer can stay within its daily quota and still hit you with 500 calls in one second.
Group consumers into plans
You don’t want to set limits per consumer by hand. Define a few plans instead, and assign each consumer to one:
| Plan | Throttle | Quota | For |
|---|---|---|---|
| Trial | 1 / sec | 1,000 / day | Partners building their integration |
| Partner standard | 5 / sec | 20,000 / day | Live partner integrations |
| Internal | 20 / sec | No quota | Your own applications |
Start with numbers your backend can actually handle, and raise them when you have data from monitoring.
Setting it up in Boomi Cloud API Management
Boomi Cloud API Management uses the same concepts: you define your API and its endpoints, group them into packages with plans that carry the limits, and issue keys to applications for a plan. The exact menu labels can change between releases, so use the steps below as a guide to the order of work.
Step 1: Define the API and its endpoint
- Create an API definition for your service, for example
ERP API. - Add an endpoint. The public side is the address consumers will call. The target (backend) side is your actual service, for example the Boomi API Service from Exposing your ERP as a REST API with Boomi. If your API is an API Service in Boomi integration, you can import it into Cloud API Management instead of defining it by hand.
- Set the endpoint’s key settings: require an API key, and choose where consumers send it (a header such as
X-API-Keyis better than a query parameter, because query strings end up in logs).
Step 2: Create a package with plans
- Create a package, for example
ERP for partners, and include the API from step 1. - Inside the package, create one plan per row of your plan table. For each plan, set the throttle (calls per second) and the quota (calls per day or month).
- Choose which endpoints and methods each plan includes. A trial plan might only get read-only endpoints.
- Decide whether keys for a plan are issued automatically or need your approval. For partner plans, approval is a sensible default.
Step 3: Onboard consumers
There are two ways to give a consumer a key:
- Through the developer portal. The partner registers, creates an application, picks a plan and receives a key (immediately or after your approval). This scales well and keeps a record of who asked for what.
- By hand. You create the application and key yourself in the dashboard and send it securely. Fine for internal applications or your first one or two partners.
Either way, create separate keys for the partner’s test and production environments.
Step 4: Close the back door
This step is easy to forget and essential: the backend must only accept traffic from the gateway. If a partner can call your Boomi runtime directly, the key and the limits are optional.
Typical options are an IP allowlist on the backend for the gateway’s addresses, credentials that only the gateway knows (configured on the endpoint’s target side), or mutual TLS between gateway and backend.
Step 5: Test the rules
# Without a key: should be rejected
curl -i https://api.example.com/erp/v1/customers/C-1042/balance
# With a trial key: should succeed
curl -i -H "X-API-Key: <trial-key>" https://api.example.com/erp/v1/customers/C-1042/balance
# Burst of calls: should start being rejected once the throttle is exceeded
for i in $(seq 1 10); do curl -s -o /dev/null -w "%{http_code}\n" -H "X-API-Key: <trial-key>" https://api.example.com/erp/v1/customers/C-1042/balance; doneNote which status code and error message the gateway returns when a limit is exceeded, and document it for consumers, so their code can wait and retry instead of failing.
Step 6: Watch the reports
After go-live, the reports per key and per plan show you who is close to their limits, who has errors and which endpoints are used. Use them to adjust the plans, and to start the conversation with a partner before their quota runs out rather than after.
Checklist
- One key per consuming application and environment
- Every plan has both a throttle and a quota
- Keys sent in a header, not in the URL
- Backend reachable only through the gateway
- Limit errors documented for consumers
- Someone reviews the usage reports regularly
For the bigger picture, including how Boomi compares with other API management tools, see API management: what it is and when you need it.