Subscriptions and rate limits

A subscription is one caller’s access in one environment: which APIs it opens, how the caller signs in, how often it may call and until when. It belongs to one gateway of that environment, so a devtest key never opens a production hostname.

Six kinds of credential#

Create one#

$ weikio subscription create finance/partner-x --env production --api invoices --type apikey --rate-limit 60/60s -y

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): ****************************************

The platform stores only a hash of the key, so the CLI prints it once and never again. 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. The issuer and the audience can be placeholders for values, so the partner’s details needn’t sit in the document:

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

A certificate subscription issues no key. It admits a caller whose client certificate an authority of the gateway signed, with the name you give in --certificate-name, on a gateway that asks for client certificates.

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 }

The key of a subscription applied from Git is minted with weikio subscription key finance/partner-x --env production, which prints it once.

/apis/finance/invoices/subscriptions

Manage a 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

rotate-key prints a new key once, and the old one stops working at the gateway’s next route table, within seconds. --expires accepts a length such as 90d or a date, and --owner records who the subscription is for. disable turns the subscription off without deleting it, and the gateway also ends a call still open under it, such as a WebSocket, within the API’s activity timeout. enable turns it back on.

Rate limits#

Limits apply at three levels, and a call must pass all of them:

A call over a limit is refused and counted on the caller’s side, never as a server failure. The subscription tables of the admin UI and weikio get subscriptions show each subscription’s calls in the last 24 hours, the calls the limit refused and its last call:

$ weikio get subscriptions --env production

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

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