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.
How Scopes Work
Section titled “How Scopes Work”Every API operation has a required scope. When a consumer requests a token, the gateway includes only the scopes their subscription entitles them to.
Subscription → has Entitlements → grant Scopes → carried in JWT → checked by Gateway → per Operation
Default Scopes
Section titled “Default Scopes”If your OAS defines security requirements with scopes, Apiway uses those. If not, Apiway generates scopes automatically:
| OAS Security | Scope Strategy |
|---|---|
| Explicit scopes defined | Uses OAS-defined scopes |
| OAuth2 but no scopes | operationId becomes the scope |
| No security defined | Client credentials + operationId scopes |
For example, an operation with operationId: "getPayments" gets the scope getPayments.
Entitlements
Section titled “Entitlements”Entitlements are the link between a subscription and the scopes it can access. They’re created during the deployment process:
- Core Service extracts per-operation scopes from the OAS
- Entitlements Service creates entitlements under the API’s technical name
- Subscription is linked to entitlements via a client command
- Gateway generates JWTs with the subscription’s entitled scopes
Entitlement Boundaries
Section titled “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
Section titled “Gateway Enforcement”The gateway’s SecurityStage reads the SecurityCheckPolicyElement on each operation and verifies:
- Token is valid — Signature, expiry, issuer
- Scopes match — The JWT carries the required scope for this operation
- 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 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
Section titled “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"