API Authentication

Every request to the Rekall API must be authenticated. Rekall supports three authentication methods: Bearer tokens, API key headers, and query parameters.

Bearer Token

The recommended authentication method is to include your API key as a Bearer token in the Authorization header. This is the most widely supported method and works with all HTTP clients.

curl https://api.rekall.ai/v1/memories \
  -H "Authorization: Bearer rk_live_abc123def456ghi789"

API Key Header

Alternatively, you can pass your API key using the x-api-key header. This method is useful for tools and frameworks that have built-in support for API key headers.

curl https://api.rekall.ai/v1/memories \
  -H "x-api-key: rk_live_abc123def456ghi789"

Query Parameter

For quick testing and debugging, you can pass the API key as a query parameter. This method is convenient for browser-based testing but should not be used in production as the key will appear in server logs and browser history.

curl "https://api.rekall.ai/v1/memories?api_key=rk_live_abc123def456ghi789"

Not recommended for production

Query parameter authentication exposes your API key in URLs, which may be logged by intermediary servers, stored in browser history, and cached by proxies. Use Bearer tokens or the x-api-key header in production environments.

Token Format

All Rekall API keys follow a consistent format that makes them easy to identify and manage. The prefix indicates the key type and environment.

PrefixTypeDescription
rk_live_LiveProduction API key with full access
rk_test_TestTest environment key, isolated from production data
rk_sandbox_SandboxSandbox key with lower rate limits for development
rk_oauth_OAuthOAuth 2.0 access token with scoped permissions

Example Requests

Below are examples of authenticated requests using different languages and HTTP clients.

Authentication Examples
# Bearer token (recommended)
curl https://api.rekall.ai/v1/memories \
  -H "Authorization: Bearer rk_live_abc123def456ghi789" \
  -H "Content-Type: application/json"


# Create a memory with authentication
curl -X POST https://api.rekall.ai/v1/memories \
  -H "Authorization: Bearer rk_live_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "episodic",
    "content": "User signed up for the Pro plan",
    "metadata": {"plan": "pro"}
  }'

Token Management

API keys can be created, rotated, and revoked from the Dashboard. Each key can be assigned specific scopes to limit its access to only the endpoints it needs.

For more details on key management and OAuth 2.0 flows, see the API Keys documentation and OAuth 2.0 guide.

Security Best Practices

Use environment variables

Never hardcode API keys in your source code. Store them in environment variables or a secrets manager.

Scope your keys

Create keys with only the scopes they need. A read-only integration should not have write access.

Rotate regularly

Rotate API keys periodically and immediately if you suspect a key has been compromised. The Developer Portal supports zero-downtime key rotation.

Use test keys for development

Use rk_test_ or rk_sandbox_ keys during development to avoid accidentally modifying production data.

Rekall
rekall