Scopes & Entitlements
Scopes control what a consumer can do. Entitlements control what scopes a consumer has. The gateway enforces both, and it resolves entitlements on every request rather than trusting a decision made when the credential was issued.
Secure by Default
Section titled “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.
- Every operation gets its own scope, added automatically, so access is controlled per operation from the first request.
- The gateway enforces the scope per operation — unauthenticated calls get 401, authenticated calls without the required scope get 403.
- Credentials are provisioned on subscribe.
Where your OAS declares security, Apiway honours it. Where pieces are missing, Apiway raises your security to this level automatically.
| OAS Security | Scope Strategy |
|---|---|
| Explicit scopes defined | Uses OAS-defined scopes |
| OAuth2 but no scopes | Apiway adds a scope for every operation |
| No security defined | Client credentials, plus a scope for every operation |
How Scopes Work
Section titled “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.
Machine-to-machine callers
Subscription → has Entitlements → grant Scopes → carried in JWT → checked by Gateway → per Operation
Human and on-behalf-of callers
Identity → holds a delegated role → resolved into Entitlements at request time → checked by Gateway → per Operation
A human or OBO token carries no scope claim by design. The caller’s authority is their delegated role, which the gateway resolves against the entitlements service when the request arrives — so a change to what someone is entitled to takes effect on their next call, not when their token expires.
Cross-Tenant Scope Intersection
Section titled “Cross-Tenant Scope Intersection”When a consumer subscribes to a producer’s API across tenants, the scopes the consumer requested are limited to the scopes declared in the producer API’s OAS before they are granted. 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
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”On every request, for each operation, the gateway verifies:
- Token is valid — Signature, expiry, issuer
- Entitlements are resolved — Live, for this caller, on this request
- Scopes match — The resolved entitlements carry the scope this operation requires
- Request proceeds — Or returns 401 (invalid token) / 403 (insufficient scopes)
The scope claim inside a token identifies the caller; it is not what authorises them. The gateway resolves entitlements from the golden source on every request and decides against that, so access withdrawn a moment ago is refused a moment later rather than surviving until the token expires.
Only the signing keys are cached, briefly. Authorisation is resolved live on every request; the single exception is when the entitlements service cannot be reached at all, described in Revocation & Token Lifetime.
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"