Scopes & Permissions
Rekall uses 14 granular scopes to control access to API resources. Scopes can be assigned to API keys, OAuth tokens, and team roles to enforce the principle of least privilege.
Least Privilege
Always assign the minimum set of scopes required for your use case. A memory reader does not need memories:write access. A search service does not need memories:delete.
All Scopes
Rekall has 14 scopes organized into 6 resource groups. Use the search box to filter by scope name or description.
| Scope | Description |
|---|---|
memories:read | Read memories, search, and list memory entries |
memories:write | Create and update memory entries |
memories:delete | Delete memory entries permanently |
entities:read | Read entity records and entity graphs |
entities:write | Create and update entity records |
entities:delete | Delete entity records permanently |
relationships:read | Read relationships between entities |
relationships:write | Create and update relationships between entities |
workflows:read | Read workflow definitions and execution history |
workflows:write | Create, update, and execute workflows |
agents:read | Read agent configurations and status |
agents:write | Create, update, and manage agents |
hives:read | Read hive configurations, members, and shared memory |
hives:write | Create, update, and manage hives and their members |
Memory Scopes
Control access to the core memory CRUD operations including episodic, semantic, procedural, and all other memory types.
| Scope | Description |
|---|---|
memories:read | Read memories, search, and list memory entries |
memories:write | Create and update memory entries |
memories:delete | Delete memory entries permanently |
Entity Scopes
Control access to entity records -- the people, places, tools, and concepts extracted from memories.
| Scope | Description |
|---|---|
entities:read | Read entity records and entity graphs |
entities:write | Create and update entity records |
entities:delete | Delete entity records permanently |
Relationship Scopes
Control access to relationships between entities in the knowledge graph.
| Scope | Description |
|---|---|
relationships:read | Read relationships between entities |
relationships:write | Create and update relationships between entities |
Workflow Scopes
Control access to procedural workflows including definitions and execution history.
| Scope | Description |
|---|---|
workflows:read | Read workflow definitions and execution history |
workflows:write | Create, update, and execute workflows |
Agent Scopes
Control access to agent configurations, status monitoring, and agent management operations.
| Scope | Description |
|---|---|
agents:read | Read agent configurations and status |
agents:write | Create, update, and manage agents |
Hive Scopes
Control access to hives -- shared memory spaces for multi-agent collaboration.
| Scope | Description |
|---|---|
hives:read | Read hive configurations, members, and shared memory |
hives:write | Create, update, and manage hives and their members |
Scope Hierarchy
Scopes follow a resource-action pattern: resource:action. Higher-privilege actions do not automatically include lower-privilege ones.
Independent scopes
Each scope is independent. Having memories:write does not grant memories:read. If your application needs to both read and write memories, you must request both scopes.
Delete requires explicit grant
Delete scopes (memories:delete, entities:delete) are always separate and must be explicitly granted. They are never included in convenience scope groups.
Cross-resource independence
Scopes for different resources are completely independent. memories:read does not grant access to entities, relationships, or any other resource.
Common Scope Combinations
For a typical agent integration, you will likely need: memories:read, memories:write, entities:read, and relationships:read.
Requesting Scopes
How you specify scopes depends on your authentication method:
// Scopes are assigned when creating the keyconst key = await rekall.apiKeys.create({name: 'Agent Memory Access',scopes: ['memories:read','memories:write','entities:read','relationships:read',],});
// Scopes are requested in the authorization URLconst authUrl = new URL('https://api.rekall.ai/v1/oauth/authorize');authUrl.searchParams.set('client_id', 'rkapp_your_client_id');authUrl.searchParams.set('scope', 'memories:read memories:write entities: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 endpointconst tokenInfo = await rekall.auth.introspect();console.log(tokenInfo.scopes);// ["memories:read", "memories:write", "entities:read"]// Or check the x-rekall-scopes response headerconst response = await fetch('https://api.rekall.ai/v1/memories', {headers: { 'Authorization': `Bearer ${apiKey}` },});const grantedScopes = response.headers.get('x-rekall-scopes');console.log(grantedScopes);// "memories:read,memories:write,entities:read"
Insufficient Scopes
If a request requires a scope that the token does not have, the API returns a 403 Forbidden response with a missing_scope error code and the required scope in the response body.
{"error": "missing_scope","message": "This action requires the 'memories:write' scope.","required_scope": "memories:write","granted_scopes": ["memories:read", "entities:read"]}
Legacy Scope Mapping
Older API keys created before the granular scope system use legacy scopes. These are automatically mapped to the new system:
| Legacy Scope | Maps To |
|---|---|
read | memories:readentities:readrelationships:readworkflows:readagents:readhives:read |
write | memories:readmemories:writeentities:readentities:writerelationships:readrelationships:writeworkflows:readworkflows:writeagents:readagents:writehives:readhives:write |
admin | All 14 scopes |
Migration
Legacy scopes will continue to work indefinitely. However, we recommend migrating to granular scopes for better security. You can update a key's scopes in the dashboard or by creating a new key with the specific scopes you need.
