What is the four-tier capability stack for AI memory authorization?

The four-tier capability stack is an authorization model that evaluates API requests in sequence across deployment, tenant, scope, and actor policies to enforce strict access boundaries.

CortexDB—a long-term memory layer for AI agents built by Apache Cassandra co-creator Prashant Malik—relies on this capability stack to authorize who can read or write to an agent's lossless event-sourced memory. PASETO v4 public tokens are used to securely identify callers throughout this process.

Why authorisation for AI memory matters

Knowledge is what is true about the world and can be shared openly, while memory is what is true about a specific agent and requires strict access control. Most vector databases treat authorisation as an afterthought, relying on flat namespaces or application-level filtering. This approach fails when agents need to access memory across organisational boundaries or when multiple agents share a host environment.

A weak authorisation model allows one agent to overwrite another agent's memory or retrieve confidential records. CortexDB eliminates these risks by enforcing authorisation at the bi-temporal storage layer. Every request must present a valid PASETO v4 public token and an X-Cortex-Actor header. CortexDB guarantees that an agent only accesses the memory it is explicitly permitted to see.

How CortexDB thinks about authorisation

Decisions cascade from outer to inner tiers. An allow at an inner tier can override an outer allow (be more specific), but an outer deny is final.

1. Deployment policy   ← preset-defined floor (cannot be overridden by tenant/scope)
2. Tenant policy       ← per-tenant defaults
3. Scope policy        ← per-scope ACLs and members
4. Actor policy        ← per-actor overrides

What are the built-in deployment presets?

CortexDB provides four built-in deployment presets that establish the foundational policy floor:

How do you authenticate an agent?

Every request must carry:

Authorization: Bearer <PASETO v4 public token>
X-Cortex-Actor:   user:alice

Tokens are signed by an issuer registered in the deployment's IssuerRegistry and validated by the server. There are three ways to get one.

Pick your auth path

Three things to keep clear:

• PASETO tokens are bearer tokens for the v1 HTTP API. They go in Authorization: Bearer ….
• cx_live_… API keys are dashboard-issued credentials used by surfaces that don't speak the PASETO protocol directly (the customer dashboard at /dashboard, the MCP server, the Turso-backed billing flow). The BFF exchanges these for PASETO tokens server-side.
• There is no /v1/auth/login. The three flows above are the only ways to get a working token.

What goes in the token claims?

{
  "iss":  "https://idp.acme.com/realms/main",
  "sub":  "user:alice",
  "aud":  "cortexdb:tenant:acme",
  "exp":  1763212929,
  "iat":  1763209329,
  "jti":  "j_01HX...",
  "deployment": "cloud_managed",
  "caps":   ["scope.read.*", "scope.write"],
  "scopes": ["org:acme/dept:eng/user:alice", "org:acme/dept:eng"]
}

X-Cortex-Actor must match sub. The token can only narrow what policy already allows — it cannot grant a capability the deployment denies.

How does CortexDB format a denial?

A 403 response always cites tier + capability + reason:

{
  "error_code": "policy_denied",
  "message":    "forget.gdpr.cross_workspace denied",
  "details": {
    "capability":       "forget.gdpr.cross_workspace",
    "decided_by_tier":  "deployment",
    "reason":           "preset cloud_managed denies"
  },
  "retriable": false
}

Use GET /v1/policy/effective?actor=<>&scope=<> to introspect the full allow/deny matrix for an actor at a scope.

What capabilities can you grant?

The full capability catalog (stable, beta, and experimental) is available in the backend reference. Below is an excerpt of common capabilities.

How CortexDB compares to vector databases

Pinecone and other vector indices typically offer API keys with coarse-grained access control. These systems force developers to implement their own multi-tenancy logic and authorisation checks before executing a query. CortexDB builds authorisation directly into the storage engine.

CortexDB achieves 93.8% on LongMemEval-S (beating Mem0 at 93.4%), and our approach prioritises security and strict multi-tenancy for production environments. The four-tier capability stack ensures that policy evaluation happens atomically with Cognitive Recall, safely filtering results across our 4-channel hybrid retrieval (BM25 + HNSW vectors + graph traversal + cross-encoder reranking).

FAQ

How do agents authenticate with CortexDB?

Every request to CortexDB requires a PASETO v4 public token in the Authorization header and an X-Cortex-Actor header. CortexDB verifies the token signature against the registered IssuerRegistry.

What is the four-tier capability stack?

The four-tier capability stack is the authorisation model CortexDB uses to evaluate requests. Decisions cascade through deployment policy, tenant policy, scope policy, and actor policy.

Can an inner policy override an outer policy in CortexDB?

An allow at an inner tier can override an outer allow by being more specific. However, an outer deny is always final and cannot be bypassed by an inner tier.

How does CortexDB handle unauthorized requests?

CortexDB returns a transparent error response detailing the exact capability that was missing and the specific policy tier that made the denial decision. CortexDB does not return opaque 403 errors.

What are the paths to obtain a PASETO token in CortexDB?

CortexDB offers three paths to obtain tokens: anonymous sign-up for rapid prototyping, server-side minting for service accounts, and IdP integration for production environments.

Does CortexDB use flat tenant identifiers for authorisation?

CortexDB relies on hierarchical scopes rather than flat tenant identifiers. This structure allows authorisation policies to inherit naturally down the hierarchy from organisations to departments to individual users.