Authentication

API Keys

Every API request requires a Bearer token:

Authorization: Bearer <RECURSIV_API_KEY>

Creating API keys

Option A: Dashboard

1. Go to recursiv.io/account/api-keys (in the app: Settings → 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 -p @recursiv/cli 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: 'Example-Passw0rd!',
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); // the generated key — 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. This is the complete list of valid scopes — anything else is rejected with an invalid_scope error:

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
// allowNoKey: auth flows don't need an API key yet — without it the
4
// constructor throws if RECURSIV_API_KEY is unset
5
const r = new Recursiv({ baseUrl: 'https://api.recursiv.io/api/v1', allowNoKey: true });
6
7
// Sign up
8
const session = await r.auth.signUp({
9
  name: 'Jane Developer',
10
  email: 'jane@example.com',
11
  password: 'Example-Passw0rd!',
12
});
13
// session: { token, user: { id, name, email, image } }
14
15
// Sign in
16
const session = await r.auth.signIn({
17
  email: 'jane@example.com',
18
  password: 'Example-Passw0rd!',
19
});
20
21
// Check session
22
const session = await r.auth.getSession(token);
23
24
// Sign out
25
await r.auth.signOut(token);

Password policy: 12–128 characters with at least one lowercase letter, one uppercase letter, one digit, and one symbol. Common/compromised passwords are rejected. Failing the policy returns a 400 with code WEAK_PASSWORD.

Autonomous onboarding (for agents)

An AI agent (or a script) can self-onboard a brand-new user with zero browser interaction: sign up → create a scoped API key → use the key. This is the recipe to go from nothing to an authenticated SDK client.

SDK one-shot — auth.signUpAndCreateKey(signUpInput, keyInput) does both steps and returns the key:

1
import { Recursiv } from '@recursiv/sdk';
2
3
// No API key yet — start anonymous
4
const anon = new Recursiv({ anonymous: true });
5
6
const { apiKey, user, session } = await anon.auth.signUpAndCreateKey(
7
  { name: 'Agent User', email: 'agent@example.com', password: 'Example-Passw0rd!' },
8
  { name: 'agent-key', scopes: ['projects:read', 'projects:write', 'agents:read', 'agents:write'] },
9
);
10
11
// Authenticated client from here on
12
const r = new Recursiv({ apiKey });

signInAndCreateKey(credentials, keyInput) is the equivalent for existing users, and verifyOtpAndCreateKey(otpInput, keyInput) for passwordless OTP flows.

REST recipe — auth endpoints live under /api/auth (Better Auth), not /api/v1:

$
# 1. Sign up → returns a session token in the response body
$
curl -X POST https://api.recursiv.io/api/auth/sign-up/email \
>
  -H 'Content-Type: application/json' \
>
  -H 'Origin: https://api.recursiv.io' \
>
  -d '{"name":"Agent User","email":"agent@example.com","password":"Example-Passw0rd!"}'
$
# → { "token": "...", "user": { "id": "...", ... } }
$
$
# (existing users: POST /api/auth/sign-in/email with {"email","password"})
$
$
# 2. Create an API key with the session token (this endpoint IS under /api/v1)
$
curl -X POST https://api.recursiv.io/api/v1/api-keys \
>
  -H 'Content-Type: application/json' \
>
  -H 'Authorization: Bearer <SESSION_TOKEN>' \
>
  -d '{"name":"agent-key","scopes":["projects:read","projects:write"]}'
$
# → { "data": { "key": "sk_live_...", ... } }  — only shown once
$
$
# 3. Use the API key for everything else (store it in an env var, never inline)
$
curl https://api.recursiv.io/api/v1/projects \
>
  -H "Authorization: Bearer $RECURSIV_API_KEY"

The Origin header is required on the /api/auth/* calls from non-browser environments (Better Auth CSRF protection) — the SDK sets it automatically.

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.