APIs and subscriptions

An API is published as versions, and an API deployment serves one version in one environment on one or more gateways. A gateway is an entrance of one environment with its hostnames, the networks that may call it, its client certificate rules and its rate limits, and the platform obtains and renews the certificate of every hostname unless you upload one.

A subscription gives a caller access to APIs on one gateway, with an API key, a query parameter, basic credentials, an OpenID Connect token, a client certificate or no credential at all. The key is shown once and only its hash is stored.

Commands on this page#

The flags every command accepts, such as --env, --project, -o and --context, are on the CLI reference page and are left out of the tables below.

weikio gateway create#

Create a gateway in an environment. --networks is required, so no gateway is left open by a forgotten flag. Give it internet to admit any caller. The reply says who can reach the gateway and where each hostname’s certificate comes from.

weikio gateway create <name> [--env E] --networks internet|CIDR,... [--hostname H ...] [--display-name S] [--served-by hub|site] [--entrance N ...] [--projects p,...] [--default] [--like G] [--relay-from G,...] [--client-certificate none|optional|required] [--authority A=CA.pem[,CA.pem] ...] [--caller-limit N/W] [--subscription-limit N/W] [--upstream-networks CIDR,...] [--max-request-size SIZE] [--server-certificate NAME=CHAIN.pem,KEY.pem ...] [--certificate-source automatic|public|platform|uploaded|AUTHORITY] [-y]

Who can run it: a platform administrator.

API: PUT /api/v1/gateways/{name}, GET /api/v1/settings/install, GET /api/v1/gateways/{like}.

Also written as weikio create gateway.

$ weikio gateway create internal --env production --hostname api.example.com --networks 10.0.0.0/8 --default -y

Target: https://hub.example, environment production (--env)
gateway internal created (environment production, revision 12)
Listens on the hub's entrance 'public' to callers in 10.0.0.0/8.
api.example.com points at this hub. Requesting its certificate from Let's Encrypt. HTTPS is served once it's issued (weikio describe gateway internal).

weikio gateway set#

Change a gateway, keeping the fields you don’t set. Fields you don’t set keep their values. Adding a hostname makes the platform obtain its certificate, unless you upload one.

weikio gateway set <name> [the flags of create] [--no-default] [--remove-hostname H ...] [--remove-server-certificate NAME ...] [--projects ""] [--remove-authority A ...] [--revoke-certificate A=leaf.pem|SHA256 ...] [--unrevoke-certificate A=leaf.pem|SHA256 ...] [--no-caller-limit] [--no-subscription-limit] [--upstream-networks ""] [--max-request-size ""] [-y]

Who can run it: a platform administrator.

API: PUT /api/v1/gateways/{name}, GET /api/v1/apim/instances.

weikio gateway diff#

Compare the rules of two gateways.

weikio gateway diff <a> <b>

Who can run it: a grant whose role has read in the environment.

API: GET /api/v1/gateways/{a}/diff/{b}.

weikio get gateways#

List the gateways.

weikio get gateways [--env E]

Who can run it: a grant whose role has read in the environment.

API: GET /api/v1/gateways?environment=.

Also written as weikio get gateway.

weikio describe gateway#

Show a gateway with its rules, certificates and what uses it.

weikio describe gateway <name>

Who can run it: a grant whose role has read in the environment.

API: GET /api/v1/gateways/{name}, GET /api/v1/apim/instances.

Also written as weikio describe gateways.

weikio get apim-instances#

List the APIM instances, with their entrances and the gateway revisions they serve.

weikio get apim-instances

Who can run it: a platform administrator. A reader of an environment sees the instances that serve its gateways.

API: GET /api/v1/apim/instances.

Also written as weikio get apim-instance.

weikio delete gateway#

Delete a gateway.

weikio delete gateway <name> [-y]

Who can run it: a platform administrator.

API: DELETE /api/v1/gateways/{name}.

Also written as weikio delete gateways.

weikio rename gateway#

Rename a gateway.

weikio rename gateway <name> <new-name>

Who can run it: a platform administrator.

API: PATCH /api/v1/gateways/{name}.

weikio api deploy#

Deploy an API version to an environment’s gateways. Without --gateways, a new deployment is served on the environment’s only gateway or on its default gateways that allow the project, and a deployment already there keeps its gateways.

weikio api deploy <p>/<api>@<v> [--env E] [--gateways G,...] [--set k=v ...] [--unset k ...] [--dry-run] [-y]

Who can run it: a grant on the project whose role has deploy in the target environment.

API: PUT /api/v1/environments/{environment}/projects/{project}/api-deployments/{api}/{v}, GET /api/v1/gateways?environment=.

$ weikio apply -f ./finance/apis/

Target: https://hub.example, project finance (from finance/project.yaml)
api finance/invoices created
api-version finance/invoices@v1 created (type proxy, rate limit 600/1m)
api-version finance/bank-notifications@v1 created (type webhook, channel bank-notification-received)
api-deployment devtest/finance/invoices@v1 created
api-subscription devtest/finance/partner-y created
Gateways updated in: devtest.

weikio api promote#

Deploy what one environment serves to another, keeping the target’s gateways and overrides. The target receives the definition the source serves, the one you tested, and keeps its own gateways, rules and overrides.

weikio api promote <p>/<api>@<v> --from E1 [--to E2] [--gateways G,...] [--dry-run] [-y]

Who can run it: a grant on the project whose role has deploy in the target environment.

$ weikio api promote finance/invoices@v1 --from devtest --to production -y

Target: https://hub.example, project finance (argument), environment production (--to)
api-deployment production/finance/invoices@v1 created (gateways internal, definition 3f9a0c1e2b4d, revision 31)
Served at https://api.example.com/invoices/v1 (gateway internal).

weikio api rollback#

Roll a deployment back to the definition it served before.

weikio api rollback <p>/<api>@<v> [--env E] [-y]

Who can run it: a grant on the project whose role has deploy in the target environment.

API: POST /api/v1/environments/{environment}/projects/{project}/api-deployments/{api}/{v}/rollback.

weikio api undeploy#

Undeploy an API version from an environment.

weikio api undeploy <p>/<api>@<v> [--env E] [-y]

Who can run it: a grant on the project whose role has deploy in the target environment.

API: DELETE /api/v1/environments/{environment}/projects/{project}/api-deployments/{api}/{v}.

weikio api set-gateways#

Change the gateways of a deployment, keeping its definition.

weikio api set-gateways <p>/<api>@<v> [--env E] [--add G,...] [--remove G,...] [--via HUB=SITE ...] [-y]

Who can run it: a grant on the project whose role has deploy in the target environment.

weikio api set-rules#

Make a gateway’s rules stricter for one deployment.

weikio api set-rules <p>/<api>@<v> [--env E] --gateway G [--networks CIDR,...] [--client-certificate optional|required] [--authority A ...] [--caller-limit N/W] [--subscription-limit N/W] | --clear [-y]

Who can run it: a grant on the project whose role has deploy in the target environment.

weikio get api-deployments#

List a project’s API deployments, in every environment unless --env is given.

weikio get api-deployments [--env E] [--project P] [--api A]

Who can run it: a grant whose role has read in the environment.

API: GET /api/v1/environments/{environment}/projects/{project}/api-deployments, GET /api/v1/projects/{project}/apis/{api}/deployments.

Also written as weikio get api-deployment.

$ weikio get api-deployments --api invoices

ENVIRONMENT   API                   DEFINITION     GATEWAYS   DEPLOYED BY        DEPLOYED               STATE
devtest       finance/invoices@v1   3f9a0c1e2b4d   devtest    anna@example.com   2026-10-08 09:14 UTC   -
production    finance/invoices@v1   3f9a0c1e2b4d   internal   anna@example.com   2026-10-08 09:20 UTC   -

weikio get apis#

List the APIs of a project.

weikio get apis [--project P]

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/apis, GET /api/v1/environments/{environment}/projects/{project}/api-deployments.

weikio describe api#

Show an API with its versions, deployments, calls of the last day and subscriptions.

weikio describe api <p>/<n>

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/apis/{name}, GET /api/v1/environments/{environment}/projects/{project}/api-subscriptions?api=, GET /api/v1/metrics/summary, GET /api/v1/traces/_related.

weikio get apiversions#

List the versions of one API.

weikio get apiversions <p>/<api>

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/apis/{api}/versions, GET /api/v1/projects/{project}/apis/{api}/deployments.

weikio describe apiversion#

Show an API version with its routes and clusters.

weikio describe apiversion <p>/<api>@<version> [--openapi]

Who can run it: a grant on the project whose role has read.

API: GET /api/v1/projects/{project}/apis/{api}/versions/{version}.

weikio delete api#

Delete an API with its versions.

weikio delete api <p>/<n> [-y]

Who can run it: a grant on the project whose role has author.

API: DELETE /api/v1/projects/{project}/apis/{name}.

weikio rename api#

Rename an API.

weikio rename api <p>/<n> <new-name>

Who can run it: a grant on the project whose role has author.

API: PATCH /api/v1/projects/{project}/apis/{name}.

weikio delete apiversion#

Delete one version of an API.

weikio delete apiversion <p>/<api>@<version> [-y]

Who can run it: a grant on the project whose role has author.

API: DELETE /api/v1/projects/{project}/apis/{api}/versions/{version}.

weikio get subscriptions#

List a project’s subscriptions with their calls of the last day.

weikio get subscriptions [--env E] [--project P] [--api A]

Who can run it: a grant whose role has read in the environment.

API: GET /api/v1/environments/{environment}/projects/{project}/api-subscriptions?api=, GET /api/v1/projects/{project}/api-subscriptions?api=.

$ 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        -         0           0         -

weikio subscription create#

Create a subscription in one environment. For apikey, queryparameter and basic, the credential is printed once as the last line, and only its hash is stored.

weikio subscription create <p>/<name> [--env E] [--gateway G] --api A[,B ...] --type apikey|queryparameter|basic|oidc|anonymous|certificate [--owner S] [--rate-limit N/W] [--expires T] [--header "k: v" ...] [--username S] [--oidc-issuer URL --oidc-audience S] [--certificate-authority A --certificate-name N]

Who can run it: a grant on the project whose role has author.

API: PUT /api/v1/environments/{environment}/projects/{project}/api-subscriptions/{name}.

Also written as weikio create subscription.

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

$ curl -H "X-Api-Key: $PARTNER_KEY" https://api.example.com/invoices/v1/pending

weikio subscription set#

Change the given fields of a subscription.

weikio subscription set <p>/<name> --env E [--api a,b] [--owner S] [--rate-limit N/W] [--expires 90d|date] [--header "Name: value" ...] [--oidc-issuer URL] [--oidc-audience S] [--certificate-authority A] [--certificate-name N]

Who can run it: a grant on the project whose role has author.

API: PUT /api/v1/environments/{environment}/projects/{project}/api-subscriptions/{name}.

weikio subscription key#

Create a subscription’s first credential and print it once. Use it for a subscription that came from Git through weikio apply, where the document has no credential.

weikio subscription key <p>/<name> [--env E] [--username S]

Who can run it: a grant on the project whose role has author.

API: POST /api/v1/environments/{environment}/projects/{project}/api-subscriptions/{name}/credential.

weikio subscription rotate-key#

Replace the credential of a subscription and print the new one once.

weikio subscription rotate-key <p>/<name> [--env E] [--username S] [-y]

Who can run it: a grant on the project whose role has author.

API: POST /api/v1/environments/{environment}/projects/{project}/api-subscriptions/{name}/credential.

weikio subscription disable#

Disable a subscription.

weikio subscription disable <p>/<name> [--env E]

Who can run it: a grant on the project whose role has author.

API: PATCH /api/v1/environments/{environment}/projects/{project}/api-subscriptions/{name}.

weikio subscription enable#

Enable a subscription.

weikio subscription enable <p>/<name> [--env E]

weikio delete subscription#

Delete a subscription.

weikio delete subscription <p>/<name> [--env E] [-y]

Who can run it: a grant on the project whose role has author.

API: DELETE /api/v1/environments/{environment}/projects/{project}/api-subscriptions/{name}.

Exit codes#

The commands on this page exit with the codes in the exit code table: 0 on success, 1 when the hub refuses a change, 2 for a usage error, 3 when the key is missing or not allowed, 4 when something isn’t found, 5 for a conflicting change, 6 when the hub can’t be reached and 8 when a document isn’t valid.

See also#

• Publish an API and call it
• Subscriptions and rate limits
• Gateways and hostnames
• Gateways at sites