Authentication

Shelv supports two auth methods:

API keys for programmatic access (Authorization: Bearer sk_...)
Session cookies for dashboard access

Route auth matrix

Route family	API key	Session	Public
`/v1/auth/*`	No	No	Yes
`/v1/shelves*`	Yes	Yes	No
`/v1/webhooks*`	Yes	Yes	No
`/v1/dashboard/*`	No	Yes	No

Session auth is intended for dashboard flows. API integrations should use API keys so requests stay decoupled from browser state. For automation and sandbox integrations, use API keys instead of session cookies so jobs are reproducible and decoupled from browser state.

Get an API key

API
Dashboard

No browser required — ideal for AI agents and developers using coding agents (Claude Code, Codex, OpenClaw).Step 1: Register an account

curl -X POST https://api.shelv.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "password": "your-secure-password"
  }'

201 Created

{
  "message": "Verification code sent to your email address. Check your inbox."
}

Step 2: Check your email for the 6-digit verification codeStep 3: Verify your email and receive an API key

curl -X POST https://api.shelv.dev/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "code": "123456"
  }'

200 OK

{
  "user": {
    "id": "usr_abc123",
    "name": "Alice",
    "email": "alice@example.com"
  },
  "apiKey": {
    "key": "sk_live_...",
    "prefix": "sk_live_...",
    "expiresAt": null
  }
}

Save apiKey.key — this is your SHELV_API_KEY. It is shown once.

Use API keys

Send the Authorization header on every request to /v1/shelves* and /v1/webhooks*:

curl https://api.shelv.dev/v1/shelves \
  -H "Authorization: Bearer sk_your_api_key"

const res = await fetch("https://api.shelv.dev/v1/shelves", {
  headers: { Authorization: `Bearer ${process.env.SHELV_API_KEY}` },
});
const shelves = await res.json();

import os
import requests

res = requests.get(
    "https://api.shelv.dev/v1/shelves",
    headers={"Authorization": f"Bearer {os.environ['SHELV_API_KEY']}"},
)
shelves = res.json()

Error model

Authentication failure (401):

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing authentication"
}

Rate limit hit (429):

{
  "code": "RATE_LIMITED",
  "message": "Too many requests, please try again later."
}

Status-gated access (409) can happen when a shelf is not yet eligible for a requested operation (for example requesting tree or archive-url before processing completes).

Rate limits

Scope	Limit
Auth routes (`/v1/auth/*`)	10 requests / 15 minutes (IP)
Auth routes (`/api/auth/**`)	10 requests / 15 minutes (IP)
Authenticated reads	120 requests / minute (user)
Authenticated writes	20 requests / minute (user)
Shelf creation (`POST /v1/shelves`)	10 requests / hour (user)

Operational best practices

Keep keys in environment variables, never source code
Use separate keys for dev/staging/prod
Rotate and revoke keys regularly

For incident response, revoke compromised keys immediately and issue replacement keys per environment.

Getting Started

Concepts

Agent Integrations

Guides

Authentication

Route auth matrix

Get an API key

Use API keys

Error model

Rate limits

Operational best practices

​Route auth matrix

​Get an API key

​Use API keys

​Error model

​Rate limits

​Operational best practices

Route auth matrix

Get an API key

Use API keys

Error model

Rate limits

Operational best practices