Overview
Summary
Access Gateway is the centralized authorization gateway that processes every permission check request from enforcers (PEPs) — Keymate SDKs, API gateway plugins, service mesh plugins, and platform components like Admin Console. It acts as the PDP Proxy and Edge Orchestrator of the Keymate platform, validating incoming requests, enriching them with identity context, evaluating access rules, and enforcing authorization decisions.
Beyond enforcement, Access Gateway serves as a burst breaker — absorbing high-frequency permission check traffic through subject-based caching before it reaches downstream authorities.
Why It Exists
In a distributed authorization architecture, permission checks from diverse sources — SDKs, API gateway plugins, and platform components — must pass through a single, well-defined enforcement point before reaching the authorization authority. Without this gateway:
- Every enforcer (PEP) call would directly hit downstream authorities, creating a scalability bottleneck.
- Token validation, introspection, and exchange logic would be duplicated across every consuming service.
- There would be no centralized place to apply access rules, enforce DPoP constraints, or cache decisions.
Access Gateway solves these problems by consolidating request validation, token mediation, access rule evaluation, and decision caching into a single, high-performance service.
Where It Fits in Keymate
Access Gateway sits between the enforcer layer (SDKs, API gateway plugins, platform components) and the authorization authorities. It is the first decision point for every authorization request in the system.
Upstream: Enforcers (PEPs) send permission check and organization context requests to the gateway. These include Keymate SDKs (Java, TypeScript, Go, .NET), API gateway plugins, service mesh plugins, and platform components (Admin Console).
Downstream: Keycloak provides token introspection and token exchange. The Keymate Authorization Decision Provider evaluates fine-grained permission decisions.
Boundaries
What Access Gateway does:
- Validates request structure, headers, and enforcer metadata
- Introspects and validates Bearer and DPoP tokens
- Evaluates access rules to determine token exchange needs and resource resolution
- Caches permission decisions, exchanged tokens, and organization context
- Enforces RFC 9449 DPoP sender-constrained token validation
- Returns structured permission responses with decision metadata headers
What Access Gateway does not do:
- Define or manage authorization policies (this is the Keymate Authorization Decision Provider's responsibility)
- Handle user authentication or session management (this remains with Keycloak)
- Serve as an API Gateway or reverse proxy (it is an authorization microservice, not a traffic proxy)
How It Works
Every incoming request passes through a structured enforcement pipeline that validates the request, checks the decision cache, and — when needed — delegates the authorization decision to the Keymate Authorization Decision Provider. The gateway also supports token exchange (RFC 8693) and resource resolution through configurable access rules.
API Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/gateway/api/v1/access/check-permission | POST | Permission check through the enforcement pipeline |
/gateway/api/v1/access/organization/context | POST | Retrieve user's organization context |
Required Headers
| Header | Description |
|---|---|
Authorization | Bearer <token> or DPoP <token> |
Keymate-Enforcer | Structured field: layer="sdk", tech="java", version="1.0.0" |
Keymate-Client-Id | OAuth client identifier |
Optional Headers
| Header | Description |
|---|---|
Keymate-Target-URI | Target URI for rule matching (e.g., /api/v1/echo/123) |
Keymate-Target-Method | HTTP method for resource resolution mode |
DPoP | DPoP proof JWT (required when using DPoP scheme) |
Diagram
Enforcer (PEP) represents the caller that initiates permission check requests. This can be a Keymate SDK (Java, TypeScript, Go, .NET), an API gateway plugin, a service mesh plugin, or the Admin Console.
Example Scenario
Scenario
A frontend SPA (demo-spa) calls the Access Gateway to check whether the current user can view employee data on the demo-api backend.
Input
- Actor: Authenticated user with a valid access token (Bearer or DPoP)
- Resource:
employee-datawith scopecan-view - Action: Permission check via SDK
- Context:
Keymate-Client-Id: demo-spa, target client isdemo-api
Expected Outcome
- Decision: GRANT
- Why: The enforcement pipeline validates the token, the access rule engine matches
demo-spa → demo-apiand triggers a token exchange. The exchanged token is used to check permissions onemployee-data:can-viewvia the Keymate Authorization Decision Provider, which returns GRANT. The result is cached for subsequent requests.
Common Misunderstandings
- "Access Gateway makes authorization decisions on its own." — No. Access Gateway enforces decisions. The actual permission evaluation is delegated to the Keymate Authorization Decision Provider.
- "Every permission check requires a full round-trip to the authorization authority." — No. Subject-based caching means that repeated checks for the same user and resource combination are served from cache.
- "DPoP tokens are forwarded to downstream services." — No. DPoP scheme is normalized to Bearer at the gateway. Downstream components never see DPoP tokens — the gateway terminates DPoP.
Access Gateway is not an API Gateway or reverse proxy. It is an authorization-only microservice. Do not route application traffic through it.
Design Notes / Best Practices
- Access Gateway uses subject-based cache keys (derived from the user's identity), meaning a token refresh for the same user produces a cache hit — no redundant authority calls.
- Cache failures are non-blocking. A cache miss or write failure gracefully falls through to the authority call.
- Always send the
Keymate-Enforcerheader. Requests without this header are rejected before the enforcement pipeline begins.
When integrating with Access Gateway, use the appropriate Keymate SDK for your platform. The SDK handles header construction, token management, and response interpretation automatically.
Related Docs
Enforcement Pipeline
Request processing stages, error codes, and response headers.
Runtime Evaluation Model
Access Rule Engine and declarative rule matching.
Decision Cache
Subject-based caching architecture.
Keymate Authorization Decision Provider
Fine-grained permission evaluation engine used by Access Gateway for authorization decisions.
What is the Access Gateway in Keymate?
Access Gateway is the PDP Proxy and Edge Orchestrator that processes every permission check request from enforcers (PEPs) — SDKs, API gateway plugins, service mesh plugins, and platform components. It validates tokens, evaluates access rules, caches decisions, and delegates permission evaluation to the Keymate Authorization Decision Provider.
Does Access Gateway make authorization decisions?
No. Access Gateway enforces decisions but does not make them. Permission evaluation is delegated to the Keymate Authorization Decision Provider. The gateway handles token validation, access rule evaluation, and decision caching.
Does Access Gateway support DPoP tokens?
Yes. Access Gateway validates DPoP sender-constrained tokens according to RFC 9449, including proof validation, replay protection, and binding verification. After validation, DPoP is normalized to Bearer — downstream services never see DPoP tokens.
How does caching work in Access Gateway?
Access Gateway uses subject-based caching, meaning cache keys are derived from the user's identity rather than the token itself. This ensures cache hits even after token refresh, as long as the user and request parameters remain the same. Only GRANT decisions are cached.