Skip to content
Weik.ioDocs
2026.2
Try Weik.io

Subscriptions and rate limits

Weik.io 2026.2

Give a caller access to your APIs with a subscription, and limit how often it may call. Product page · Video

Watch: Open it to a caller: a key and a limit, 3:28

The video opens the API to a caller through a subscription with an API key and a rate limit.

On this page

Create a subscription to give a caller access to your APIs in one environment. The subscription belongs to one gateway of that environment, so its credential opens the APIs only on that gateway’s hostnames.

Credential types#

Type The caller sends
apikey A key in the X-Api-Key header
queryparameter A key in the ?x-api-key= query parameter
basic A username and a password
oidc An OpenID Connect token from the issuer and for the audience you set
certificate A client certificate with the name you set, signed by an authority the gateway trusts
anonymous Nothing, because the API is open to every caller the gateway admits

The gateway removes the X-Api-Key header from the requests it forwards.

Create one#

Terminal
$ weikio subscription create finance/partner-x --env production --api invoices --type apikey --rate-limit 60/1m -y
You see
Target: https://hub.example, project finance (argument), environment production (--env)
api-subscription production/finance/partner-x created (gateway internal, type apikey, APIs invoices, rate limit 60/1m)

To rotate the key later:
  weikio subscription rotate-key finance/partner-x --env production

API key (shown once): ****************************************

Weik.io stores only a hash of the key, so the CLI can print the key only once. Give it to the partner through the channel you use for secrets.

A partner that signs in with its own identity provider gets an oidc subscription:

Terminal
$ weikio subscription create finance/partner-z --env production --api invoices --type oidc --oidc-issuer https://login.partner.example --oidc-audience invoices-api

The issuer and the audience can be placeholders for values, so the partner’s details don’t have to be in the document.

A certificate subscription issues no key. On a gateway that accepts client certificates, it admits a caller whose certificate has the name you set in --certificate-name and is signed by one of the gateway’s authorities.

In Git, a subscription is an api-subscription document in the environment’s folder:

finance/production/apis/partner-x.yaml
apiVersion: weik.io/v1
kind: api-subscription
metadata: { name: partner-x, project: finance, environment: production }
spec:
  apis: [invoices]
  type: apikey
  rateLimit: { permitLimit: 60, window: 1m }

For a subscription applied from Git, weikio subscription key finance/partner-x --env production prints the key once.

/apis/finance/invoices/subscriptions
The Subscriptions of the invoices API: partner-x-test in devtest, and ap-portal in production. The subscriptions partner-x and partner-y are in production too. Each subscription has an API key and a rate limit, and a count of its calls in 24 hours.The Subscriptions of the invoices API: partner-x-test in devtest, and ap-portal in production. The subscriptions partner-x and partner-y are in production too. Each subscription has an API key and a rate limit, and a count of its calls in 24 hours.The Subscriptions of the invoices API: partner-x-test in devtest, and ap-portal in production. The subscriptions partner-x and partner-y are in production too. Each subscription has an API key and a rate limit, and a count of its calls in 24 hours.The Subscriptions of the invoices API: partner-x-test in devtest, and ap-portal in production. The subscriptions partner-x and partner-y are in production too. Each subscription has an API key and a rate limit, and a count of its calls in 24 hours.
In Subscriptions, you see the consumers of an API in each environment and the key type and the rate limit of each.

Manage a subscription#

Change a subscription with weikio subscription:

Terminal
$ weikio subscription rotate-key finance/partner-x --env production
$ weikio subscription set finance/partner-x --env production --expires 90d --owner "Partner X integration team"
$ weikio subscription disable finance/partner-x --env production
Command or flag What it does
rotate-key Prints a new key once. The old key stops working as soon as the gateway has the new one.
--expires Sets when the subscription expires, as a length such as 90d or as a date.
--owner Records who the subscription is for.
disable Turns the subscription off without deleting it. The gateway also ends a call still open under it, such as a WebSocket, within the API’s activity timeout.
enable Turns the subscription back on.

Rate limits#

Where Set with Counts
The API version rateLimit: { permitLimit: 1200, window: 1m } in the api-version The calls of each subscription that sets no limit of its own
The subscription --rate-limit 60/1m, or rateLimit in the document The calls of one subscription, across every APIM instance
The gateway --caller-limit on weikio gateway create or set The calls of one caller address in each APIM instance
The gateway --subscription-limit on weikio gateway create or set The calls of each subscription when neither the subscription nor the API version sets a limit

The gateway answers a call over any of these limits with HTTP 429 and an empty body, and counts it as a failure on the caller’s side. The Retry-After header of that answer has the number of seconds to wait, at least 1.

With several APIM instances, a subscription can make up to an eighth more calls than its limit.

weikio get subscriptions shows how many calls each subscription made in the last 24 hours and how many of them went over a limit:

Terminal
$ weikio get subscriptions --env production
You see
NAME        PROJECT   APIS       GATEWAY    TYPE     ACTIVE   RATE LIMIT   EXPIRES   CALLS 24H   LIMITED   LAST CALL
partner-x   finance   invoices   internal   apikey   yes      60/1m        -         1,284       12        2026-09-16 13:04 UTC

The subscription tables of the admin UI show the same two counts.

A deployment can make one gateway’s rules stricter for its API, but not looser. weikio api set-rules finance/invoices@v1 --env production --gateway internal --caller-limit 30/1m lowers the caller limit for this API only.

Sign in to the live demo

Sign in with the shared viewer account. It can open every screen of the example projects but can't change anything.

E-mail
viewer@demo.weik.io
Password
try-weikio-live-demo
Open the live demo