> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# Authentication

## API Keys

Every API request requires a Bearer token:

```text
Authorization: Bearer <RECURSIV_API_KEY>
```

### Creating API keys

**Option A: Dashboard**

1. Go to [recursiv.io/account/api-keys](https://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**

```bash
npx -p @recursiv/cli recursiv auth login
# Prompts for email + password → saves API key to .env
```

**Option C: Programmatically**

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv();

// First, sign in to get a session
const session = await r.auth.signIn({
  email: 'you@example.com',
  password: 'Example-Passw0rd!',
});

// Then create an API key using the session token
const key = await r.auth.createApiKey(
  {
    name: 'my-agent-key',
    scopes: ['projects:read', 'projects:write', 'agents:read', 'agents:write'],
  },
  session.token,
);

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:

| Scope                 | What it allows                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `projects:read`       | List projects, get details, view deployments and logs                                       |
| `projects:write`      | Create/delete projects, deploy, execute code, manage sandboxes                              |
| `agents:read`         | List agents, get details, view conversations                                                |
| `agents:write`        | Create/update/delete agents, chat, grant project access                                     |
| `posts:read`          | List and search posts                                                                       |
| `posts:write`         | Create/update/delete posts, react to posts                                                  |
| `communities:read`    | List communities, view members                                                              |
| `communities:write`   | Create communities, join/leave                                                              |
| `chat:read`           | List conversations, read messages                                                           |
| `chat:write`          | Send messages, create DMs and groups                                                        |
| `users:read`          | Get user profiles, followers, following                                                     |
| `users:write`         | Update user profiles, follow/unfollow                                                       |
| `organizations:read`  | List organizations, view members and settings                                               |
| `organizations:write` | Create/update organizations, manage members                                                 |
| `notifications:read`  | List notifications                                                                          |
| `notifications:write` | Mark notifications read, manage preferences                                                 |
| `tags:read`           | List and get tags                                                                           |
| `tags:write`          | Create and delete tags                                                                      |
| `uploads:write`       | Upload files                                                                                |
| `wallet:read`         | View wallet balances                                                                        |
| `wallet:write`        | Wallet operations                                                                           |
| `commands:read`       | Read command results                                                                        |
| `commands:write`      | Execute AI commands                                                                         |
| `settings:read`       | Read user settings                                                                          |
| `settings:write`      | Update user settings                                                                        |
| `billing:read`        | View billing and usage                                                                      |
| `billing:write`       | Manage subscriptions                                                                        |
| `memory:read`         | Read agent memory (facts, decisions)                                                        |
| `memory:write`        | Write agent memory                                                                          |
| `databases:read`      | View databases and credentials, run read queries                                            |
| `databases:write`     | Create databases, run write queries                                                         |
| `storage:read`        | List buckets and objects, get download URLs                                                 |
| `storage:write`       | Create buckets, upload and delete objects                                                   |
| `admin`               | Platform administration (restricted — only platform admins can create keys with this scope) |

## Authentication methods

Recursiv supports three authentication methods:

| Method              | Use case                                                                           | How it works                                                                         |
| ------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **API Key**         | SDK, CLI, server-to-server, local MCP                                              | `Authorization: Bearer <RECURSIV_API_KEY>` header                                    |
| **Session**         | Browser apps, dashboard                                                            | Cookie-based session from `r.auth.signIn()`                                          |
| **OAuth connector** | Connecting an AI client (Claude Desktop, ChatGPT, Gemini) to the hosted MCP server | Add a custom connector at `https://api.recursiv.io/mcp` and sign in — no key to copy |

For most SDK integrations, use API keys. Session auth powers the web dashboard and browser apps.

### Connecting an AI client (OAuth)

The hosted MCP server at `https://api.recursiv.io/mcp` speaks the standard MCP OAuth flow, so a no-code AI client connects by URL and sign-in — no key handling on the user's side:

1. In the client, add a custom connector and paste `https://api.recursiv.io/mcp`.
2. The client discovers the authorization server, registers itself (dynamic client registration), and opens a Recursiv sign-in.
3. After the user approves, the platform issues an access token and provisions a per-user credential scoped to what that user can already reach.

This is the recommended way to connect Claude Desktop, Claude.ai, ChatGPT, and the Gemini web app / CLI. See [MCP → Hosted connect](/guides/ai-tools/mcp-claude-cursor#hosted-connect-recommended). The `sk_live_*` API key remains the right choice for the SDK, CLI, and the local MCP connector used by coding agents.

## User auth flows

```typescript
import { Recursiv } from '@recursiv/sdk';

// allowNoKey: auth flows don't need an API key yet — without it the
// constructor throws if RECURSIV_API_KEY is unset
const r = new Recursiv({ baseUrl: 'https://api.recursiv.io/api/v1', allowNoKey: true });

// Sign up
const session = await r.auth.signUp({
  name: 'Jane Developer',
  email: 'jane@example.com',
  password: 'Example-Passw0rd!',
});
// session: { token, user: { id, name, email, image } }

// Sign in
const session = await r.auth.signIn({
  email: 'jane@example.com',
  password: 'Example-Passw0rd!',
});

// Check session
const session = await r.auth.getSession(token);

// Sign out
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:

```typescript
import { Recursiv } from '@recursiv/sdk';

// No API key yet — start anonymous
const anon = new Recursiv({ anonymous: true });

const { apiKey, user, session } = await anon.auth.signUpAndCreateKey(
  { name: 'Agent User', email: 'agent@example.com', password: 'Example-Passw0rd!' },
  { name: 'agent-key', scopes: ['projects:read', 'projects:write', 'agents:read', 'agents:write'] },
);

// Authenticated client from here on
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`:

```bash
# 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:

| Auth Method                              | Scope                        | Use Case                                       |
| ---------------------------------------- | ---------------------------- | ---------------------------------------------- |
| **SDK API Key** (the generated key)      | Auto-scoped to the key's org | Normal usage — your agents see only your tasks |
| **`DISPATCHER_API_KEY`** (shared secret) | Admin — sees all orgs        | Internal ops, cross-org monitoring             |

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:

```bash
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.