# API Gateway Access Decisions: Separate Credentials, Routes, and Resource Permissions > Design API access around four distinct questions: caller identity, credential authority, route admission, and permission to act on a specific resource. Canonical URL: https://www.devobs.io/articles/api-gateway-access-decisions/ By: Amara Okafor Published: 2026-10-10T11:31:13.256Z Updated: 2026-10-10T11:31:13.256Z Section: Authorization Design API gateway access around four separate questions: which principal the request represents, what access the credential permits, whether the route admits the request, and whether the principal may act on the specific resource. For a protected resource operation, do not treat route admission alone as proof of resource permission. The same enforcement layer may handle both checks, but make the resource check explicit. The goal is separate responsibilities, not necessarily separate services. ## Separate the four access questions Use the following decision model when designing a protected API: | Question | Decision to make | Boundary to preserve | | --- | --- | --- | | Which principal does the request represent? | Identify the user or client principal, retaining any delegation context needed by the policy. | Account management is not a substitute for authenticating the request. | | What access does the credential permit? | Establish trusted credential context and evaluate its constraints on the requested operation. | A valid credential is not an unrestricted grant. | | Does this route admit the request? | Evaluate the request against the route's access policy. | Reaching an endpoint must not imply access to every object behind it. | | May this principal act on this resource? | Evaluate the requested action against the particular object and its permission model. | Preserve the resource identifier and action through to enforcement. | Ory's documentation describes building blocks for these responsibilities: - **Kratos:** Ory documents its Kratos-based Ory Identities service as providing identity and user management, including login, registration, recovery, and account-management flows. [Ory Kratos documentation](https://www.ory.com/docs/network/kratos/intro) - **Hydra:** Ory documents its Hydra-based service as providing OAuth 2.0 and OpenID Connect, with use cases including delegated access on behalf of users and server-to-server authorization without a user present. In Ory Network, the service connects to Ory Identities by default but can use another user-management system. [Ory Hydra documentation](https://www.ory.com/docs/network/hydra) - **Keto:** Ory documents fine-grained permissions, including relationships such as a user being a reader of a particular document, with permission inheritance through groups, roles, and hierarchies. [Ory Keto documentation](https://www.ory.com/docs/network/keto) Use these roles to plan the integration. Do not assume that selecting components establishes the complete request path or determines where every check runs. ## Define how the API obtains trusted credential information Before writing route policy, specify how the enforcement layer obtains and validates the credential information on which that policy depends. RFC 7662 defines token introspection: an authorized protected resource queries an authorization server for token metadata. The response requires an `active` boolean; fields such as `scope` and `client_id` are optional. Introspection can convey the token's access rights and authorization context, but do not assume every response contains all the context your policy needs. [RFC 7662](https://www.rfc-editor.org/rfc/rfc7662) RFC 9068 defines a profile for OAuth access tokens encoded as JWTs, including claims and resource-server validation rules intended to support interoperability. [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) For your deployment, document the accepted token format or profile and the component responsible for validation. Do not assume that a JWT-shaped token conforms to RFC 9068, or rely on selecting an OAuth provider as a substitute for configuring the gateway's validation behavior. Also define how the trusted credential context maps to the principal used by the permission model. Specify what happens when required principal or authorization information is missing. Keep credential authority separate from resource permission. In the example below, define an application-specific `documents:read` scope as permission to attempt document reads—not as permission to read every document. ## Specify who enforces the route decision Ory documents two relevant Oathkeeper arrangements: - **Reverse proxy:** Oathkeeper rejects unauthorized requests and forwards authorized requests to the configured upstream. - **Access Control Decision API:** Another gateway asks Oathkeeper for a decision and remains responsible for admitting or rejecting the original request. Both arrangements are described in the [Oathkeeper documentation](https://www.ory.com/docs/oathkeeper). Choose one explicitly so that responsibility for forwarding is unambiguous. Oathkeeper's documented rule matching considers the HTTP method, path, scheme, and host. A request is denied if no access rule matches. Matching can use `X-Forwarded-Method`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Uri` when those headers are present. [Oathkeeper rule matching](https://www.ory.com/docs/oathkeeper) A matching rule is not itself an authorization grant. Ory documents authentication and authorization steps after matching: invalid credentials or failed authorization result in denial. Mutation can then add session information to a request forwarded upstream. [Oathkeeper decision engine](https://www.ory.com/docs/oathkeeper) Request reconstruction therefore belongs in the integration design. Have trusted infrastructure establish the forwarded values used for decisions rather than accepting arbitrary client-supplied versions. Apply the same boundary discipline to identity headers consumed by the application. For the Decision API, the documented success result is HTTP `200`; any other status must not allow the request. Configured error handling can produce other responses, including redirects, which require support from the calling reverse proxy. Depending on the rule's mutator, a successful response can also contain additional or changed headers. [Oathkeeper Decision API](https://www.ory.com/docs/oathkeeper) Write down how the gateway interprets that response and which identity-related headers it forwards. Do not assume that the decision response itself forwards the original request to the application. ## Authorize the document, not just the endpoint Consider an illustrative request: ```text GET /documents/document-42 ``` For this API, design the route policy to establish that the credential may attempt document reads. Then evaluate whether the principal may read `document-42` before returning its contents. Keto's documented Ory Permission Language example supplies a concrete resource policy: a document has editors and viewers; editors may write; editors or viewers may read. OPL is defined as a subset of TypeScript. [Keto permission-model example](https://www.ory.com/docs/network/keto) Under that specific example policy, the expected object-level decisions are: | Relationship to the requested document | Read | Write | | --- | --- | --- | | Editor | Allow | Allow | | Viewer only | Allow | Deny | | Neither editor nor viewer | Deny | Deny | Keep the object identifier in the permission check. A relationship to one document should not be treated as a relationship to another unless the permission model explicitly establishes it. Place enforcement where the system can reliably bind the principal, action, and target resource together. That may be application code consulting a permission service, or another deliberately designed enforcement layer. If the gateway performs the resource check, make that binding part of its integration contract. Do not let a route-only decision stand in for a missing resource check. ## Test the boundaries, not just the happy path For the protected document API, turn the design into acceptance tests: - **Change only the document ID.** Keep the caller and credential fixed; verify that permission for one document does not grant access to an unrelated document. - **Change the operation.** Under the example policy, a viewer should pass the read check and fail the write check. - **Use an unmatched route.** Verify Oathkeeper's documented denial behavior and ensure the request does not reach the protected operation. - **Return a non-200 decision.** Verify that a gateway using Oathkeeper's Decision API does not forward the protected request as authorized. - **Supply client-controlled forwarding or identity headers.** Verify that they cannot override the trusted context selected by your integration. - **Omit required credential context.** Verify that missing information does not silently become a more permissive principal or policy decision. - **Make a required decision unavailable.** Specify and test a policy that does not convert a timeout or indeterminate result into permission to proceed. The architectural goal is a complete decision chain for the protected operation: establish the principal, evaluate credential authority, enforce route policy, and authorize access to the concrete resource. ## Source references - - - - - -