Skip to main content

Tiered API Monetization

Create Free, Pro, and Enterprise API tiers with separate rate limits and quota enforcement. Each tier maps to a policy; each partner or customer is assigned to a tier via a client-profile pair.

Typical scenario: A fintech platform offers a public API. Free users get 100 calls/day, Pro users get 10,000 calls/day, and Enterprise partners get 1,000,000 calls/day with priority access and expanded endpoints.

Prerequisites​

  • You are signed in to the Management UI as an admin or editor
  • At least one published collection exists with the API endpoints you want to monetize

Step 1 — Create a policy for each tier​

Policies define the rate limit and daily quota applied to a client.

  1. Open Clients & Profiles → Policies, then click New policy.
  2. Create three policies:

Free tier:

  • Name: tier-free
  • Rate limit: 10 requests per minute
  • Daily quota: 100 requests

Pro tier:

  • Name: tier-pro
  • Rate limit: 100 requests per minute
  • Daily quota: 10,000 requests

Enterprise tier:

  • Name: tier-enterprise
  • Rate limit: 1,000 requests per minute
  • Daily quota: 1,000,000 requests

Save each policy before creating the next.

Step 2 — Create a profile for each tier​

Profiles set the authentication method and bind to a policy. One profile per tier allows you to control allowed methods and add IP restrictions per tier.

  1. Open Clients & Profiles → Profiles, click New profile.
  2. Create three profiles:

Free profile:

  • Name: profile-free
  • Auth method: Token
  • Allowed methods: GET only
  • Policy: tier-free

Pro profile:

  • Name: profile-pro
  • Auth method: Token
  • Allowed methods: GET, POST
  • Policy: tier-pro

Enterprise profile:

  • Name: profile-enterprise
  • Auth method: Token (or JWT / mTLS for higher assurance)
  • Allowed methods: GET, POST, PUT, DELETE
  • Policy: tier-enterprise

Step 3 — Create client records and assign tiers​

Each customer or partner has one client record. Assign them to the appropriate tier profile.

Example: onboarding a Free-tier customer

  1. Open Clients & Profiles → Clients, click New client.
  2. Set:
    • Name: customer-webhooks-io
    • Status: Enabled
  3. Save. Note the generated Client ID.
  4. Open the client record and navigate to Profiles.
  5. Assign the profile profile-free.
  6. Generate a bearer token and store it.

Example: upgrading a customer to Pro

  1. Open the existing client record.
  2. Remove the profile-free assignment.
  3. Assign profile-pro.
  4. Optionally generate a new token.
  5. Save.
tip

To upgrade a customer's tier, swap the profile on their client record. No gateway restart or redeploy is required.

Step 4 — Assign collection access per tier​

Free and Pro customers may only access certain collections. Enterprise customers get access to all.

  1. Open each collection (e.g. payments-api, premium-data-api).
  2. Under the Access tab, add the clients who should have access.
  3. Leave premium collections unassigned for Free-tier clients — they will receive 403 Forbidden if they attempt access.
CollectionFreeProEnterprise
public-data-api✓✓✓
payments-api—✓✓
premium-data-api——✓

Step 5 — Enable portal access by tier​

Give each customer portal access so they can self-serve their API keys and test calls.

  1. Open each client record, go to the Portal access tab.
  2. Add their email address under Authorized emails.
  3. Customers can now sign in to the developer portal and see only the collections they are permitted to access.

Step 6 — Verify enforcement​

Test each tier from the command line.

Free tier — rate limit test:

# Should return 200
curl -i https://gateway.example.com/public-data-api/v1/items \
  -H "X-Client-ID: <free-client-id>" \
  -H "Authorization: Bearer <free-token>" \
  -H "X-Profile-ID: profile-free"

# After 10 requests/min — should return 429
# Retry-After header tells the client when to resume

Free tier — collection restriction test:

# Should return 403 (client not assigned to this collection)
curl -i https://gateway.example.com/payments-api/v1/transactions \
  -H "X-Client-ID: <free-client-id>" \
  -H "Authorization: Bearer <free-token>" \
  -H "X-Profile-ID: profile-free"

Enterprise tier — expanded access test:

# Should return 200
curl -i https://gateway.example.com/premium-data-api/v1/insights \
  -H "X-Client-ID: <enterprise-client-id>" \
  -H "Authorization: Bearer <enterprise-token>" \
  -H "X-Profile-ID: profile-enterprise"

Expected results:

ScenarioExpected response
Free tier, allowed collection200
Free tier, restricted collection403 Forbidden
Free tier, rate exceeded (>10/min)429 Too Many Requests
Pro tier, POST request200
Free tier, POST request405 Method Not Allowed
Any tier, missing X-Client-ID401 Unauthorized

Monitor usage per tier​

Open Logs → Request Logs and filter by Client ID to see per-customer usage.

For usage-based billing:

  • Export request logs to your data warehouse or billing pipeline
  • Group by client_id, collection, and date to calculate daily counts
  • Set alerts when customers approach their daily quota ceiling

Next steps​