Authentication

API Keys

Every API request requires a Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxx

Creating API keys

Option A: Dashboard

1. Go to recursiv.io/dashboard/api-keys
2. Click Create API Key
3. Select the scopes you need
4. Save the key — it’s only shown once

Option B: CLI

$
npx recursiv auth login
$
# Prompts for email + password → saves API key to .env

Option C: Programmatically

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv();
4
5
// First, sign in to get a session
6
const session = await r.auth.signIn({
7
  email: 'you@example.com',
8
  password: 'secure12345!',
9
});
10
11
// Then create an API key using the session token
12
const key = await r.auth.createApiKey(
13
  {
14
    name: 'my-agent-key',
15
    scopes: ['projects:read', 'projects:write', 'agents:read', 'agents:write'],
16
  },
17
  session.token,
18
);
19
20
console.log(key.key); // sk_live_... — save this, it's only shown once

Scopes

API keys are scoped with fine-grained permissions. When creating a key, specify only the scopes your application needs.

Session auth vs API key auth

Recursiv supports two authentication methods:

For most SDK integrations, use API keys. Session auth is used by the web dashboard and browser-based apps.

User auth flows

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv({ baseUrl: 'https://api.recursiv.io/api/v1' });
4
5
// Sign up
6
const session = await r.auth.signUp({
7
  name: 'Jane Developer',
8
  email: 'jane@example.com',
9
  password: 'secure12345!',
10
});
11
// session: { token, user: { id, name, email, image } }
12
13
// Sign in
14
const session = await r.auth.signIn({
15
  email: 'jane@example.com',
16
  password: 'secure12345!',
17
});
18
19
// Check session
20
const session = await r.auth.getSession(token);
21
22
// Sign out
23
await r.auth.signOut(token);

Organization scoping

SDK API keys are tied to an organization. When you make API calls, operations are automatically scoped to that organization — you don’t need to pass organization_id on every request.

This applies to:

• Dispatcher — r.dispatcher.tasks() returns only your org’s tasks
• Memory — r.memory.facts.list() returns only your org’s facts
• Projects, agents, communities — all filtered to your org

Dispatcher auth: SDK key vs admin key

The dispatcher supports two auth paths:

For most use cases, use an SDK API key. The DISPATCHER_API_KEY is only needed for admin tooling that needs cross-org visibility.

Best practices

1. Use the narrowest scopes possible. If your app only reads posts, don’t request posts:write.
2. Store API keys securely. Use environment variables, not source code.
3. Use separate keys per environment. Dev, staging, and production should each have their own key.
4. Rotate keys periodically. Create a new key, update your deployment, then revoke the old one.
5. Never expose keys in client-side code. API keys should only be used server-side. For browser apps, use session auth.

Anonymous access

The anonymous sandbox lets anyone try Recursiv with zero setup:

$
curl -X POST https://api.recursiv.io/api/v1/sandbox/try \
>
  -H 'Content-Type: application/json' \
>
  -d '{"code": "console.log(1 + 1)", "language": "typescript"}'

No API key. No signup. Rate limited to 10 executions per IP per day.