API Keys

API keys are personal access tokens that authenticate requests to the Rekall API. They are the simplest way to get started and are ideal for server-side integrations, scripts, and agent workflows.

Key Prefix

All Rekall API keys are prefixed with rk_ for production keys and rk_test_ for sandbox keys. This makes it easy to identify and manage keys across environments.

Creating API Keys

You can create API keys from the Rekall dashboard or programmatically via the API.

Via Dashboard

  1. Navigate to Settings → API Keys
  2. Click Create New Key
  3. Give the key a descriptive name (e.g., "Production Backend")
  4. Select the scopes the key should have access to
  5. Optionally set an expiration date
  6. Click Generate and copy the key immediately

Copy Your Key

API keys are only displayed once at creation time. If you lose a key, you will need to create a new one. Store it securely in a password manager or secrets vault.

You can also create keys programmatically:

import Rekall from '@rekall/sdk';


const rekall = new Rekall({
  apiKey: process.env.REKALL_API_KEY,
});


const newKey = await rekall.apiKeys.create({
  name: 'CI Pipeline Key',
  scopes: ['memories:read', 'memories:write'],
  expiresIn: '90d',
});


console.log(newKey.key); // rk_abc123...
// Store this key securely -- it won't be shown again

Key Format

Rekall API keys follow a consistent format that makes them easy to identify and manage:

TypePrefixExample
Productionrk_rk_a1b2c3d4e5f6...
Sandboxrk_test_rk_test_x9y8z7w6...

Keys are 48 characters long (including the prefix) and contain alphanumeric characters. The prefix allows automatic environment detection -- requests made with rk_test_ keys are always routed to the sandbox environment.

Passing API Keys

You can pass your API key in three ways. The Bearer token method is recommended.

Bearer Token (Recommended)

Pass the key in the Authorization header:

const response = await fetch('https://api.rekall.ai/v1/memories', {
  headers: {
    'Authorization': `Bearer ${process.env.REKALL_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

x-api-key Header

Alternatively, use the x-api-key header:

const response = await fetch('https://api.rekall.ai/v1/memories', {
  headers: {
    'x-api-key': process.env.REKALL_API_KEY!,
    'Content-Type': 'application/json',
  },
});

Query Parameter

Not Recommended

Passing API keys as query parameters is supported but not recommended. Query parameters may be logged in server access logs, browser history, and proxy servers. Use header-based authentication instead.

Query parameter (not recommended)
curl "https://api.rekall.ai/v1/memories?api_key=rk_your_api_key_here"

Scoping Keys

API keys can be scoped to limit their access. Rekall supports 14 granular scopes that control which resources a key can access.

Creating a scoped key
const readOnlyKey = await rekall.apiKeys.create({
  name: 'Read-Only Dashboard',
  scopes: [
    'memories:read',
    'entities:read',
    'relationships:read',
  ],
});


// This key can only read data -- writes will return 403 Forbidden

Least Privilege

Always create keys with the minimum scopes required. A key used only for reading memories should not have memories:write or memories:delete access.

Key Rotation

Regular key rotation reduces the risk of compromised credentials. Rekall supports zero-downtime key rotation by allowing multiple active keys simultaneously.

Rotation Steps

  1. Create a new API key with the same scopes as the existing key
  2. Update your application to use the new key
  3. Deploy the change and verify requests are succeeding with the new key
  4. Revoke the old key once all traffic has migrated
// Step 1: Create a new key with the same scopes
const newKey = await rekall.apiKeys.create({
  name: 'Production Backend (rotated)',
  scopes: ['memories:read', 'memories:write', 'entities:read'],
  expiresIn: '90d',
});


// Step 2: Update your environment variable
// REKALL_API_KEY=rk_new_key_here


// Step 3: Deploy and verify


// Step 4: Revoke the old key
await rekall.apiKeys.revoke('rk_old_key_id');

Revoking Keys

Revoked keys are invalidated within 60 seconds across all Rekall edge locations. Revocation is permanent and cannot be undone.

// Revoke a specific key by ID
await rekall.apiKeys.revoke('key_id_here');


// List all active keys
const keys = await rekall.apiKeys.list();
console.log(keys.map(k => ({
  id: k.id,
  name: k.name,
  lastUsed: k.lastUsedAt,
  scopes: k.scopes,
})));

Compromised Keys

If you suspect a key has been compromised, revoke it immediately. Do not wait for the rotation cycle. You can create a new key at any time from the dashboard.

Security Best Practices

lock

Store API keys in environment variables or a secrets manager, never in source code.

sync

Rotate keys every 90 days. Set calendar reminders or use automated rotation.

shield

Use the minimum scopes required. Avoid creating keys with full admin access.

visibility_off

Never expose API keys in client-side code, Git repositories, or public channels.

timer

Set expiration dates on keys. Expired keys are automatically revoked.

monitoring

Monitor key usage in the dashboard. Investigate unexpected spikes in activity.

science

Use sandbox keys (rk_test_) for development and testing. They have no access to production data.

Next Steps

Learn about scopes and permissions →Set up OAuth for third-party apps →Try sandbox mode for testing →Follow the quickstart guide →
Rekall
rekall