Skip to main content
Shelv supports two auth methods:
  • API keys for programmatic access (Authorization: Bearer sk_...)
  • Session cookies for dashboard access

​
Route auth matrix

Route familyAPI keySessionPublic
/v1/auth/*NoNoYes
/v1/shelves*YesYesNo
/v1/webhooks*YesYesNo
/v1/dashboard/*NoYesNo
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

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"

​
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

ScopeLimit
Auth routes (/v1/auth/*)10 requests / 15 minutes (IP)
Auth routes (/api/auth/**)10 requests / 15 minutes (IP)
Authenticated reads120 requests / minute (user)
Authenticated writes20 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.