Authentication

Overview

Satori uses API keys for authentication, powered by Clerk’s API key management system. Each API key is tied to a specific tenant (you, the developer), and all memories stored using that key are isolated to your account.

API Key Structure

Satori API keys follow this format:

sk_satori_[random_string]

API keys are secrets that grant full access to your memory data. Never commit them to version control or expose them in client-side code.

Creating an API Key

Visit satori.dev/dashboard and sign in with your account.

Navigate to API Keys

Click on “API Keys” in the sidebar navigation.

Create a new key

Click “Create API Key” and give it a descriptive name:

Production Key
Development Key
Testing Key

Use different keys for different environments (development, staging, production) to easily revoke access if needed.

Copy your key

Your API key will be displayed once. Copy it immediately and store it securely.

You won’t be able to see the key again after closing this dialog. If you lose it, you’ll need to create a new one.

Add to environment variables

Store your API key in your environment variables:

.env.local

SATORI_API_KEY=sk_satori_...
SATORI_URL=https://api.usesatori.sh

Using API Keys

Server-Side Usage (Recommended)

Always use API keys on the server side, never in client-side code:

app/api/chat/route.ts

import { memoryTools } from '@usesatori/tools';

export async function POST(req: Request) {
  // ✅ Safe: Server-side API route
  const tools = memoryTools({
    apiKey: process.env.SATORI_API_KEY!,
    baseUrl: process.env.SATORI_URL!,
    userId: 'user-123',
  });
  
  // ... rest of your code
}

Client-Side (Never Do This)

Never expose your API key in client-side code:

// ❌ NEVER DO THIS
const tools = memoryTools({
  apiKey: 'sk_satori_...', // Exposed to users!
  baseUrl: 'https://api.usesatori.sh',
  userId: 'user-123',
});

Authentication Headers

When making direct HTTP requests to the Satori API, include your API key in the x-api-key header:

const response = await fetch('https://api.usesatori.sh/trpc/memory.search', {
  method: 'GET',
  headers: {
    'x-api-key': process.env.SATORI_API_KEY!,
    'Content-Type': 'application/json',
  },
});

curl -X GET 'https://api.usesatori.sh/trpc/memory.search' \
  -H 'x-api-key: sk_satori_...' \
  -H 'Content-Type: application/json'

import requests

response = requests.get(
    'https://api.usesatori.sh/trpc/memory.search',
    headers={
        'x-api-key': os.environ['SATORI_API_KEY'],
        'Content-Type': 'application/json'
    }
)

Tenant Isolation Model

Satori uses a two-level isolation model:

Level 1: Tenant (API Key Owner)

Your API key identifies you as the tenant. All memories created with your key belong to your account.

// When you create an API key in the dashboard
const apiKey = await clerkClient.apiKeys.create({
  name: 'Production Key',
  subject: 'user_372Icb...', // Your Clerk user ID
});

Level 2: End Users (Your Application’s Users)

Within your tenant, you can have unlimited end users, each with isolated memories:

// Alice's memories
const aliceTools = memoryTools({
  apiKey: process.env.SATORI_API_KEY!,
  baseUrl: process.env.SATORI_URL!,
  userId: 'alice', // Your app's user identifier
});

// Bob's memories (completely separate)
const bobTools = memoryTools({
  apiKey: process.env.SATORI_API_KEY!,
  baseUrl: process.env.SATORI_URL!,
  userId: 'bob',
});

Think of it like this: Your API key is your “account”, and userId is how you separate your users’ data within your account.

API Key Verification Flow

Here’s what happens when you make a request:

Request includes API key

Your application sends a request with the x-api-key header:

headers: {
  'x-api-key': 'sk_satori_...'
}

Satori verifies with Clerk

The Satori server verifies the key with Clerk:

const verified = await clerkClient.apiKeys.verify(apiKey);
// verified.subject = "user_372Icb..." (your tenant ID)

Request is scoped to tenant

All database queries are automatically scoped to your tenant:

const memories = await db
  .select()
  .from(memories)
  .where(
    and(
      eq(memories.clerkUserId, 'user_372Icb...'), // Your tenant
      eq(memories.userId, 'alice') // Specific user
    )
  );

Managing API Keys

List Your Keys

View all your active API keys:

import { trpc } from '@/lib/trpc';

function APIKeysPage() {
  const { data: keys } = trpc.keys.list.useQuery();
  
  return (
    <div>
      {keys?.map((key) => (
        <div key={key.id}>
          <h3>{key.name}</h3>
          <p>Created: {key.createdAt}</p>
          <p>Last used: {key.lastUsedAt}</p>
        </div>
      ))}
    </div>
  );
}

Revoke a Key

Revoke an API key to immediately prevent all access:

const revokeKey = trpc.keys.revoke.useMutation();

await revokeKey.mutateAsync({ id: 'key-uuid' });

Revoking a key immediately stops all applications using that key. Make sure to update your applications with a new key before revoking the old one.

Security Best Practices

Use environment variables

Store API keys in environment variables, never hardcode them:

// ✅ Good
apiKey: process.env.SATORI_API_KEY!

// ❌ Bad
apiKey: 'sk_satori_...'

Rotate keys regularly

Create a new API key and update your applications, then revoke the old key:

Create new key in dashboard
Update environment variables in all environments
Deploy updates
Revoke old key

Use different keys per environment

Separate keys for development, staging, and production:

# .env.development
SATORI_API_KEY=sk_satori_dev_...

# .env.production
SATORI_API_KEY=sk_satori_prod_...

Monitor key usage

Check the “Last used” timestamp in your dashboard to detect unused or compromised keys.

Never commit keys to Git

Add environment files to .gitignore:

.gitignore

.env.local
.env*.local
.env.development.local
.env.production.local

Rate Limiting

API keys are subject to rate limits to prevent abuse:

Limit Type	Value
Requests per minute	100
Memories per user	Unlimited
Concurrent requests	10

Need higher limits? Contact support to discuss enterprise plans.

Error Handling

Handle authentication errors gracefully:

try {
  const memories = await client.searchMemories('query');
} catch (error) {
  if (error.message.includes('Unauthorized')) {
    console.error('Invalid API key');
    // Notify admin, rotate key, etc.
  } else if (error.message.includes('rate limit')) {
    console.error('Rate limit exceeded');
    // Implement backoff strategy
  }
}

Next Steps

Memory Isolation

Learn more about tenant and user isolation

API Reference

Explore the API key management endpoints

Integration Guide

See authentication in action

Troubleshooting

Fix common authentication issues

​Overview

​API Key Structure

​Creating an API Key

​Using API Keys

​Server-Side Usage (Recommended)

​Client-Side (Never Do This)

​Authentication Headers

​Tenant Isolation Model

​Level 1: Tenant (API Key Owner)

​Level 2: End Users (Your Application’s Users)

​API Key Verification Flow

​Managing API Keys

​List Your Keys

​Revoke a Key

​Security Best Practices

​Rate Limiting

​Error Handling

​Next Steps

Memory Isolation

API Reference

Integration Guide

Troubleshooting

Overview

API Key Structure

Creating an API Key

Using API Keys

Server-Side Usage (Recommended)

Client-Side (Never Do This)

Authentication Headers

Tenant Isolation Model

Level 1: Tenant (API Key Owner)

Level 2: End Users (Your Application’s Users)

API Key Verification Flow

Managing API Keys

List Your Keys

Revoke a Key

Security Best Practices

Rate Limiting

Error Handling

Next Steps