FGA Cache

The Descope AuthZ Cache is a high-performance authorization cache service that accelerates Fine-Grained Authorization (FGA) checks by caching authorization data locally within your cluster.

By deploying this service alongside your application, you can significantly reduce latency for authorization checks and improve overall application performance.

Overview

The AuthZ Cache service applies to select authorization operations that use Descope's FGA service (/v1/mgmt/fga/* endpoints).

The cache service acts as a local cache layer between your application and Descope's authorization services. It automatically syncs with remote authorization data and provides fast, local access to relationship and permission information needed for FGA checks.

How It Works

The AuthZ Cache service:

1. Connects to Descope: Uses your management key to authenticate and fetch authorization data
2. Caches Locally: Stores direct and indirect relations in local memory for fast access using LRU (Least Recently Used) eviction when caches reach their configured size limits
3. Syncs Automatically: Periodically polls Descope's services (based on AUTHZCACHE_REMOTE_POLLING_INTERVAL_IN_MILLIS) to keep the cache up-to-date
4. Serves Requests: Responds to FGA check requests from your application SDKs with cached data

When your application performs any FGA operations (ReBAC relation checks, ABAC attribute evaluations, schema queries, etc.), the SDK first queries the local cache service.

If the data is available and fresh, it's returned immediately. If not, or if the cache needs to refresh, it falls back to querying Descope's authz service directly.

Cache Behavior

The cache uses a sophisticated two-tier caching strategy:

• Direct Relations Cache: Stores direct relationships (e.g., user1 directly owns file1)
• Indirect Relations Cache: Stores indirect relationships (e.g., user1 owns file1 through group membership)

Cache Lookup Order:

1. Check direct relations cache first
2. If not found, check indirect relations cache
3. If still not found, query Descope SDK and update cache with result

Cache Invalidation:

• Schema changes: Purges all caches (direct + indirect) to ensure consistency
• Relation additions/deletions: Updates direct cache incrementally, purges indirect cache (since indirect relations may have changed)
• Remote polling: Detects changes via polling and removes affected resources/targets from cache
• Polling errors: Purges all caches for safety to prevent serving stale data

Negative Caching: Both allowed (true) and denied (false) authorization results are cached to avoid repeated remote queries for the same checks.

Write Operations: When you create or delete relations through the cache service, the cache is updated immediately - you don't need to wait for the next polling cycle. This ensures write operations are immediately reflected in subsequent read operations.

Remote Polling

The service automatically starts polling for remote changes when a project cache is created. Polling behavior:

• Polls Descope's GetModified API for changes since the last poll time
• On schema changes → purges all caches
• On relation changes → removes affected resources/targets from direct cache, purges indirect cache
• If no cached relations exist → skips remote call but invalidates schema cache to detect schema changes
• On polling errors → purges all caches for safety

The polling interval is configurable via AUTHZCACHE_REMOTE_POLLING_INTERVAL_IN_MILLIS (minimum 15,000ms).

Run with Docker

In order to deploy the FGA Cache service using Docker, you can use the following command:

docker run -d \
  --name authzcache \
  -p 8189:8189 \
  -e HTTP_HOST=0.0.0.0 \
  -e DESCOPE_MANAGEMENT_KEY=your_management_key_here \
  descope/authzcache:latest

The service exposes the following port 8189 for HTTP REST API. The service uses gRPC internally and exposes HTTP REST API via gRPC-Gateway.

Configuration

Required Environment Variables

• DESCOPE_MANAGEMENT_KEY - Your Descope management key for authentication. This key must have FGA read/write permissions. The management key is used by the cache service to authenticate with Descope's services.

Optional Environment Variables

• DESCOPE_BASE_URL - Custom Descope base URL (default: production Descope service)
• CONTAINER_HTTP_PORT - HTTP gateway port (default: 8189)
• AUTHZCACHE_SDK_DEBUG_LOG - Enable debug logging of the internally used Descope SDK (TRUE/FALSE, default: FALSE)
• AUTHZCACHE_DIRECT_RELATION_CACHE_SIZE_PER_PROJECT - Direct relation cache size per project (default: 1,000,000). Note: This is per project - if you have multiple projects, each maintains its own cache of this size.
• AUTHZCACHE_INDIRECT_RELATION_CACHE_SIZE_PER_PROJECT - Indirect relation cache size per project (default: 1,000,000). Note: This is per project - if you have multiple projects, each maintains its own cache of this size.
• AUTHZCACHE_REMOTE_POLLING_INTERVAL_IN_MILLIS - Remote polling interval in milliseconds (default: 15,000). Minimum value is 15,000ms (15 seconds) - any value below this will be automatically increased to 15,000ms.

In Your Application

To have the Descope SDK use this cache container for accelerating FGA operations (including ReBAC and ABAC checks), pass its URL via the FGACacheURL configuration field when initializing your Descope SDK client. Point the URL to the running container/service inside your local environment or cluster.

Once configured, all authorization operations that use the FGA service will benefit from the local cache.

URL Configuration

• Local Docker container: http://localhost:8189 (or the mapped host/port you selected)
• Kubernetes service: Use the internal service DNS name, e.g., http://authzcache.default.svc.cluster.local:8189

SDK Examples

package main
 
import (
	"context"
	"github.com/descope/go-sdk/descope/client"
)
 
const (
	YourProjectID                     = "your-project-id"
	YourFGAReadWriteApprovedMGMTKey   = "your-management-key" // must have proper FGA permissions
	URLToThisContainer                = "http://localhost:8189" // or cluster service URL
)
 
func main() {
	ctx := context.Background()
 
	// Initialize the Descope SDK client with the AuthZ cache URL
	err := client.InitDescopeSDKClient(ctx, &client.DescopeSDKClientConfig{
		ProjectID:   YourProjectID,
		MgmtKey:     YourFGAReadWriteApprovedMGMTKey,
		FGACacheURL: URLToThisContainer,
	})
	if err != nil {
		panic(err)
	}
 
	// Continue with your application logic...
}

API Endpoints

The service exposes REST API endpoints for managing FGA schemas, relations, and performing authorization checks.

All endpoints require authentication with a bearer token via the Authorization header in the following format: Bearer <Descope Project ID>:<Management Key>

{
  "dsl": "string"
}

curl -X POST "http://localhost:8189/v1/mgmt/fga/schema" \
  -H "Authorization: Bearer <Project ID>:<Management Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": "model AuthZ 1.0\ntype user\ntype doc\n  relations\n    define owner: [user]\n    define viewer: [user]"
  }'

Deployment Considerations

• The cache automatically syncs with remote authorization data based on the polling interval environment variable

• Ensure the container is reachable from where your code runs (network policy / firewall / service mesh settings)

• The cache size can be configured per project to match your authorization data volume. Each project maintains its own isolated cache.

• Caches use LRU (Least Recently Used) eviction - when a cache reaches its size limit, the least recently used entries are evicted to make room for new entries.

• For production deployments, consider running multiple cache instances behind a load balancer for high availability

• The service supports multiple projects simultaneously - each project gets its own cache instance with isolated data and independent polling