Subscribing to APIs

A subscription grants a consumer access to a deployed API or Product. It manages credentials, rate limits, RU quotas, and entitlements.

Apiway supports two shapes:

API subscription — one subscription per API + major version. Used when a consumer needs exactly one API.
Product subscription — one bundle subscription covering every member API in the Product. A single credential works across the bundle; each member is independently auth’d at the gateway.

curl -X POST https://core.api.apiway.net/v1/subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalogueId": "cat-abc123",
    "slaVariant": "Foundation",
    "securityTypes": ["OAuth2"],
    "scopes": ["read:payments", "write:payments"]
  }'

For cross-tenant subscribes (subscribing to a producer in another Apiway tenant), the call references the marketplace catalogueId. The pipeline onboards the API into your tenant as a local mirror, negotiates with the producer asynchronously, and stamps the credentials on an upstream subscription row once the producer approves.

Product Subscription

Subscribing to a Product creates a single bundle subscription row for the (Product, Consumer, Tenant):

ApiProductId = X, ApiId = null. Carries the shared credential and product-level SLA tier.
No per-member subscription rows exist. The gateway enforces access per member API via product-scoped reverse lookup at validation time — each member proxy accepts any token whose backing credential is authorised for the product.

A Product is a virtual grouping of member APIs, not a security surface. The bundle credential authorises calls across every member API, but tokens are minted at each member API’s own token endpoint — see Credential Management.

Platform API
Management UI

curl -X POST https://core.api.apiway.net/v1/subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productCatalogueId": "cat-prod-xyz",
    "slaVariant": "Foundation",
    "securityTypes": ["OAuth2"]
  }'

The bundle row lands immediately with Status = Requested and promotes to Approved once member fanout completes. Each member API goes through its own governance flow (which auto-approves on consumer-side mirrors in typical cross-tenant configurations).

Subscription Lifecycle

State	Meaning
Requested	Created, awaiting governance outcome
Approved	Credentials active, gateway honours calls
Rejected	Governance refused; no credential issued
Revoked	Access terminated, credentials invalidated

Revoking a bundle subscription cascades to every gateway-side artefact for the same (Product, Consumer, Tenant) — the bundle credential is invalidated and member proxies’ product-scoped reverse lookup returns no authorised JWKS, so every member API stops honouring calls. There are no per-member subscription rows to revoke separately.

What a Subscription Includes

Component	Description
Credentials	OAuth client (ID + secret) or API key — provisioned automatically
Entitlements	Scopes granted, intersected with the target API’s OAS-declared scopes
Rate limit	Requests per time window (configurable per tier)
RU quota	Resource unit budget for metered billing
RU period	Billing cycle — daily, monthly, quarterly, annual, or pay-as-you-go
Alert threshold	Percentage of RU quota that triggers a soft warning

SLA Tiers

Producers can define multiple SLA tiers in OpenSLA:

Tier	Rate Limit	RU Quota	Price
Free	10 req/min	1,000 RU/month	Free
Standard	100 req/min	50,000 RU/month	Per-unit pricing
Enterprise	1,000 req/min	Unlimited	Custom

On subscribe, the consumer selects a tier (or Apiway recommends one based on estimated usage). The producer’s approval freezes the chosen tier as a consumer-side SLA snapshot — subsequent producer tier edits do not retroactively change the contract.

Credential Management

Credentials are owned by the subscription. For API subscriptions, one credential set per subscription. For Product subscriptions, the bundle row holds a shared credential authorised across every member API.

Tokens are always minted at a specific member API’s /oauth2/v2/token endpoint — never at a product-level endpoint. Each issued token is audience-scoped to one member API, with scopes intersected against that API’s OAS (RFC 6749 §3.3). To call multiple member APIs the client mints one token per API using the shared bundle credential.

A Product does not expose its own /oauth2/v2/token endpoint. Per-API tokens keep Authorization headers below the upstream proxy header limit (no scope-union explosion across large bundles), preserve OAuth2’s intersection contract, and let each member API enforce its own scope set against its own OAS without cross-member leakage.

For cross-tenant subscriptions specifically, two related rows exist on the consumer side:

Upstream row (IsUpstream = true) — holds the credential used to call the producer’s gateway.
Internal row (IsUpstream = false) — holds the credential consuming teams use to authenticate at the consumer’s own gateway.

Both rows are stamped with the same consumer-side SLA snapshot so the SLA tier shows correctly on both views.

Key Rotation

Generate new credentials for the subscription
Update your application configuration with the new credentials
Revoke old credentials

Apiway tracks credential expiry via SubscriptionSecurity.ExpiresOn and the daily CredentialExpiryAlertService dispatches 14-day-ahead alerts to consumer, API owner, and dependency owners.

External API Subscriptions

For external APIs (Stripe, Twilio, or any non-Apiway third-party) the consumer onboarding pipeline brings them under management — see External APIs for the flow.