Scopes & Permissions

All Scopes

Rekall has 14 scopes across 7 resources (memory, agent, webhook, user, org, apikey, oauth). Use the search box to filter by scope name or description.

Memory Scopes

Control access to the core memory CRUD operations including episodic, semantic, procedural, and all other memory types. Note that memory:delete is a separate grant from memory:write.

Agent Scopes

Control access to agent constellations. agent:read covers listing, runs, lineage, and thought streams; agent:spawn covers creating agents and starting runs; agent:manage covers mutation and deletion. Agent tokens (at_…) carry a subset of these scopes and are enforced per-route.

Webhook Scopes

Control access to webhook subscriptions and their delivery history.

User Scopes

Control access to the authenticated user's own profile and account state.

Hive / Org Scopes

Control access to hives (organizations) -- shared memory spaces for team and multi-agent collaboration -- including membership and role management.

Admin Scopes

Control credential management: API keys and OAuth applications.

Scope Hierarchy

Scopes follow a resource-action pattern: resource:action. Higher-privilege actions do not automatically include lower-privilege ones.

Requesting Scopes

How you specify scopes depends on your authentication method:

// Scopes are assigned when creating the key
const key = await rekall.apiKeys.create({
  name: 'Agent Memory Access',
  scopes: [
    'memory:read',
    'memory:write',
    'agent:read',
    'agent:spawn',
  ],
});

// Scopes are requested in the authorization URL
const authUrl = new URL('https://api.rekall.ai/v1/oauth/authorize');
authUrl.searchParams.set('client_id', 'rkapp_your_client_id');
authUrl.searchParams.set('scope', 'memory:read memory:write agent:read');
// ...other parameters

Checking Permissions

You can check what scopes a token or key has by calling the introspection endpoint or checking the response headers.

// Check scopes via the introspection endpoint
const tokenInfo = await rekall.auth.introspect();
console.log(tokenInfo.scopes);
// ["memory:read", "memory:write", "agent:read"]

// Or check the x-rekall-scopes response header
const response = await fetch('https://api.rekall.ai/v1/memories', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
});
const grantedScopes = response.headers.get('x-rekall-scopes');
console.log(grantedScopes);
// "memory:read,memory:write,agent:read"

{
  "error": "missing_scope",
  "message": "This action requires the 'memory:write' scope.",
  "required_scope": "memory:write",
  "granted_scopes": ["memory:read", "agent:read"]
}

Legacy Scope Mapping

Older API keys created before the granular scope system use legacy scopes. These are automatically mapped to the new system: