Subscriptions and rate limits
Weik.io 2026.2Give 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.
This part of the video couldn't be loaded.
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- header |
queryparameter |
A key in the ? 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#
$ weikio subscription create finance/partner-x --env production --api invoices --type apikey --rate-limit 60/1m -yTarget: 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:
$ weikio subscription create finance/partner-z --env production --api invoices --type oidc --oidc-issuer https://login.partner.example --oidc-audience invoices-apiThe 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:
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.




Manage a subscription#
Change a subscription with weikio subscription:
$ 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. |
-- |
Sets when the subscription expires, as a length such as 90d or as a date. |
-- |
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- |
The calls of each subscription that sets no limit of its own |
| The subscription | --, or rateLimit in the document |
The calls of one subscription, across every APIM instance |
| The gateway | -- on weikio gateway create or set |
The calls of one caller address in each APIM instance |
| The gateway | -- 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:
$ weikio get subscriptions --env productionNAME 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 UTCThe 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.