Scopes & Entitlements

Scopes control what a consumer can do. Entitlements control what scopes a consumer has. The gateway enforces both — with zero runtime database lookups.

Secure by Default

You do not need to write a single line of security configuration. Upload an OAS without a securitySchemes block, without security on operations, without scopes on flows — Apiway still produces a fully-secured API:

• OAuth 2.0 client_credentials is registered as the default flow.
• One scope per operation is auto-generated as {METHOD}:{path} (e.g. GET:/payments, POST:/payments/{id}/refund).
• The gateway enforces the scope per operation — unauthenticated calls get 401, authenticated calls without the required scope get 403.
• Credentials are provisioned on subscribe.

If your OAS does declare security, Apiway honours it — the auto-generation only kicks in when the OAS is silent.

OAS Security	Scope Strategy
Explicit scopes defined	Uses OAS-defined scopes
OAuth2 but no scopes	{METHOD}:{path} per operation
No security defined	Client credentials + {METHOD}:{path} per operation

How Scopes Work

Every API operation has a required scope. When a consumer requests a token, the gateway issues a JWT carrying only the scopes their subscription entitles them to.

Subscription → has Entitlements → grant Scopes → carried in JWT → checked by Gateway → per Operation

Cross-Tenant Scope Intersection

When a consumer subscribes to a producer’s API across tenants, the scopes the consumer requested are intersected with the scopes declared on the producer API’s OAS before being stamped on the subscription. Scopes the API doesn’t declare are dropped and logged.

This matters most for Product subscribes, where the wizard unions scopes across every member API of the bundle — without this filter, a member subscription would carry scopes from other APIs in the product (e.g. apis:read leaking onto a payments member). The intersection is enforced on the producer side at receive, so it’s authoritative regardless of what the consumer sends.

Entitlements

Entitlements are the link between a subscription and the scopes it can access. They’re created during the deployment process:

1. Core Service extracts per-operation scopes from the OAS
2. Entitlements Service creates entitlements under the API’s technical name
3. Subscription is linked to entitlements via a client command
4. Gateway generates JWTs with the subscription’s entitled scopes

Entitlement Boundaries

Entitlements are scoped to the major version of an API. When you deploy v2 of an API, it gets its own set of entitlements — independent of v1. This prevents a v1 subscription from accessing v2 operations.

Gateway Enforcement

The gateway’s SecurityStage reads the SecurityCheckPolicyElement on each operation and verifies:

1. Token is valid — Signature, expiry, issuer
2. Scopes match — The JWT carries the required scope for this operation
3. Request proceeds — Or returns 401 (invalid token) / 403 (insufficient scopes)

This check is entirely local — the gateway reads scopes from the JWT and compares them to the operation’s policy. No network calls, no database queries.

Roles

Roles are bundles of scopes. Instead of granting individual scopes, you assign a role that includes a curated set of operations:

Role	Scopes Included
payments-reader	getPayments, getPaymentById, listTransactions
payments-admin	All payments-reader scopes + createPayment, refundPayment

Roles simplify consumer onboarding — especially when APIs have many operations.

Managing Entitlements

Navigate to the subscription detail page in the management UI. The Entitlements tab shows which scopes are granted and allows you to modify access. Or query via the platform API:

curl https://entitlements.api.apiway.net/v1/entitlements?subscriptionKey={key} \
  -H "Authorization: Bearer $TOKEN"