Organization Context Endpoint

Scope

This reference covers the Organization Context API endpoint exposed by the Access Gateway. The endpoint retrieves the authenticated user's organization assignment and returns it as a structured response. Results are cached per subject with support for negative caching (users without organization assignments).

Definitions

Term	Description
Organization Context	The user's assigned organization within the Keymate tenant model
Negative Caching	Caching the absence of a result to prevent repeated downstream lookups
Subject	The user's identity extracted from token introspection, used as the cache key

Endpoint

POST /gateway/api/v1/access/organization/context

Request

Required Headers

Header	Value	Description
Authorization	Bearer <token> or DPoP <token>	Valid access token

Request Body

No body required. The endpoint extracts the user identity from the access token.

Response

Successful Response — Organization Found

200 OK — User has an organization assignment

{
  "status": true,
  "errorMessage": null,
  "organization": {
    "userId": "user-123",
    "tenants": [
      {
        "tenantId": "tenant-456",
        "tenantName": "Acme Corp",
        "departments": [
          {
            "departmentId": "dept-789",
            "departmentName": "Engineering"
          }
        ]
      }
    ]
  }
}

Field	Type	Description
status	boolean	true when the request was processed
errorMessage	string | null	null when organization is found; descriptive message when not
organization	object | null	Organization context object, or null if no assignment
organization.userId	string	The user's unique identifier
organization.tenants	array	List of tenants the user belongs to
tenants[].tenantId	string	Tenant identifier
tenants[].tenantName	string	Tenant display name
tenants[].departments	array	Departments within the tenant
departments[].departmentId	string	Department identifier
departments[].departmentName	string	Department display name

Successful Response — No Organization

200 OK — User has no organization assignment

{
  "status": true,
  "errorMessage": "No organization assigned for this user",
  "organization": null
}

info

Both responses return status: true with HTTP 200. The absence of an organization is indicated by organization: null and a descriptive errorMessage. This result is cached to prevent repeated downstream queries.

Error Responses

HTTP Status	Cause
401 Unauthorized	Missing or invalid access token
500 Internal Server Error	Unexpected error during processing

Caching Behavior

The organization context endpoint uses subject-based caching:

• Positive results: The full organization context is cached.
• Negative results: When a user has no organization assignment, a "no organization" marker is cached to prevent repeated downstream queries.
• Cache failures: Non-blocking — cache failures fall through to the downstream query.

Allowed Values / Behavior

Response Scenario	status	organization	errorMessage
Organization found	true	Organization object	null
No organization	true	null	Descriptive message
Token invalid	N/A	N/A	HTTP 401 error response

Used By

• Keymate SDKs — Java, TypeScript, Go, .NET SDKs call this endpoint to retrieve organization context
• API gateway plugin — Gateway plugins can retrieve organization context for routing decisions

Minimal Example

cURL — Retrieve organization context

curl -X POST https://access-gateway.example.com/gateway/api/v1/access/organization/context \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Invalid Example

Missing Authorization header — returns 401

curl -X POST https://access-gateway.example.com/gateway/api/v1/access/organization/context

401 Unauthorized

{
  "status": "ERROR",
  "errorCode": "MISSING_BEARER_TOKEN",
  "errorDescription": "Authorization header with Bearer token is required"
}

Notes

• The organization context is resolved independently from the permission check pipeline. It has its own endpoint and its own cache.
• Negative caching is essential for performance. Without it, users without organizations would trigger a downstream query on every request.
• Organization assignments change infrequently, so the cache uses a longer TTL compared to permission decisions. For immediate propagation of organization changes, cache invalidation may be needed.

warning

Organization context caching uses a longer TTL compared to permission caching because organization assignments change infrequently. If your use case requires real-time organization changes, consider cache invalidation strategies.

Related Docs

Decision Cache

Full caching architecture including organization cache details.

Overview

Access Gateway API endpoints and capabilities.

Enforcement Pipeline

Request processing pipeline for permission checks.

Keymate Authorization Decision Provider

Fine-grained permission evaluation engine used by Access Gateway.