Skip to main content

Overview

Summary​

Keymate SDKs enable applications to enforce authorization decisions by communicating with the Access Gateway. Each SDK acts as a Policy Enforcement Point (PEP) — the component within your application that checks whether a user has permission to perform an action on a resource. The Access Gateway orchestrates authorization by forwarding evaluation requests to the Authorization Decision Provider, which performs the actual policy evaluation. The Access Gateway also handles token validation and decision caching. The SDK provides the client-side interface for your programming language.

This page helps you choose the right SDK for your platform, understand the common authorization model that all SDKs share, and identify the capabilities available in each language.

Why It Exists​

Applications need a reliable, language-native way to enforce authorization decisions without directly managing HTTP calls, token attachment, retry logic, or fail-closed behavior. Keymate SDKs abstract these concerns into a consistent client library so that developers can focus on business logic while the SDK handles communication with the Access Gateway.

Where It Fits in Keymate​

The SDK sits at the application layer as the Policy Enforcement Point (PEP). It does not evaluate policies — it delegates that responsibility to the Access Gateway and the Authorization Decision Provider. The SDK's role is to send permission check requests, attach tokens, cache responses, and return GRANT or DENY decisions to your application code.

Boundaries​

  • What SDKs cover: permission checks (single, multiple, list all), token management (Bearer, DPoP), organization context retrieval, retry with backoff, response caching, and token lifecycle events.
  • What SDKs do not cover: OAuth flows (login, token acquisition, token refresh orchestration), policy authoring, resource or scope definition, user management, or identity provider configuration. These are handled by Keycloak and the Keymate Admin Console respectively.

Available SDKs​

SDKLanguageRuntimePackageStatus
JavaScript SDKTypeScript / JavaScriptNode.js 18+, Browser@keymate/access-sdk-jsAvailable
Java SDKJava / KotlinJVM (Java 8+)keymate-sdk-core, keymate-sdk-springAvailable
.NET SDKC#.NET 8+—Planned
Golang SDKGoGo 1.21+—Planned

Choose Your SDK​

Select the SDK based on your application platform:

  • Node.js backend or browser SPA → JavaScript SDK — supports both server-side and client-side environments with automatic storage detection
  • Spring Boot or standalone Java application → Java SDK — includes Spring Boot auto-configuration and annotation-based permission enforcement (@CheckPermission, @ListPermissions)
  • .NET application → .NET SDK — planned
  • Go service → Golang SDK — planned

Common Authorization Model​

All Keymate SDKs share the same authorization model and communicate with the same Access Gateway endpoint. Regardless of which SDK you use, the following concepts apply:

Permission Checks​

Every SDK provides three permission check methods:

MethodPurpose
Check single permissionVerify whether a user has a specific scope on a specific resource
Check multiple permissionsEvaluate several resource-scope pairs in a single request
List all permissionsRetrieve all granted permissions for the current user

Each check returns a GRANT or DENY status for every requested resource-scope pair.

Fail-Closed Security​

All SDKs implement a fail-closed security model: if the Access Gateway is unreachable, times out, or returns an unexpected error, the SDK returns DENY by default. This prevents unauthorized access during infrastructure failures.

The one exception is 401 Unauthorized responses, which are propagated to the calling application so it can trigger a token refresh or redirect to login.

Organization Context​

All SDKs support retrieving the authenticated user's organization context — the hierarchy of tenants, organizations, and departments the user belongs to. This enables organization-aware authorization decisions in multi-tenant applications.

Token Management​

SDKs handle two token types transparently:

Token TypeStandardUse Case
BearerRFC 6750Standard OAuth 2.0 access tokens
DPoPRFC 9449Sender-constrained tokens that bind to a cryptographic key pair, preventing token replay

The SDK does not handle OAuth flows (login, token acquisition). Your application obtains the access token from the identity provider (Keycloak) and passes it to the SDK. The SDK then attaches the token to every Access Gateway request automatically.

Token Lifecycle Events​

SDKs emit events for token state changes, enabling your application to respond to authentication transitions:

  • Token set — a new access token has been configured
  • Token expired — the Access Gateway returned 401, indicating the token is no longer valid
  • Token cleared — the token was explicitly removed (logout, revocation)

SDK Capabilities Comparison​

CapabilityJavaScriptJava
Single permission checkYesYes
Multiple permission checkYesYes
List all permissionsYesYes
Organization contextYesYes
Bearer token supportYesYes
DPoP token supportYesYes
Token lifecycle eventsYesYes
Automatic retry with backoffYesYes
Response cachingYesYes
Spring Boot annotations—Yes
Browser supportYes—

Integration Architecture​

All SDKs follow the same integration pattern:

  1. The user authenticates with Keycloak and your application receives an access token
  2. Your application passes the token to the Keymate SDK
  3. When a permission check is needed, the SDK sends the request to the Access Gateway
  4. The Access Gateway evaluates policies via the Keymate Authorization Decision Provider and returns a GRANT or DENY decision
  5. Your application enforces the decision

Example Scenario​

Scenario​

A Node.js backend application needs to verify whether the authenticated user can view employee records before returning data from the /api/employees endpoint.

Input​

  • Actor: Authenticated user with a valid access token
  • Resource: employee-data
  • Action: can-view
  • Context: GET /api/employees

Expected Outcome​

  • Granted: The Access Gateway confirms the user has the can-view scope on employee-data. The SDK returns status: 'GRANT' and the application serves the employee list.
  • Denied: The user lacks the required scope. The SDK returns status: 'DENY' and the application returns 403 Forbidden.
  • Token expired: The Access Gateway returns 401. The SDK emits a tokenExpired event so the application can refresh the token and retry.

Next Steps​

JavaScript SDK

Node.js and browser SDK with TypeScript support

Java SDK

JVM SDK with Spring Boot annotations

Access Gateway

Centralized authorization orchestrator

Authorization Models

RBAC, ABAC, ReBAC policy concepts