Skip to main content

​
Authentication

The Shelv API supports two authentication methods: API keys for programmatic access and session cookies for the dashboard.

​
API Keys

API keys are the primary way to authenticate with the Shelv API. They provide full access to all public API endpoints.

​
Creating an API Key

  1. Sign in to the Shelv dashboard
  2. Go to Settings > API Keys
  3. Click Create API Key and give it a name
  4. Copy the key — it’s only shown once

​
Using an API Key

Include your API key in the Authorization header with the Bearer prefix: 
curl https://api.shelv.dev/api/shelves \
  -H "Authorization: Bearer sk_your_api_key"

import requests

headers = {"Authorization": "Bearer sk_your_api_key"}
response = requests.get("https://api.shelv.dev/api/shelves", headers=headers)

​
Security Best Practices

  • Store API keys in environment variables, never in source code
  • Rotate keys periodically — you can create multiple keys and delete old ones
  • Use separate keys for different environments (development, staging, production)

​
Error Responses

If authentication fails, you’ll receive a 401 response: 
{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing authentication"
}

​
Rate Limits

API requests are rate-limited for authenticated users:
OperationLimit
Read operations (GET)120 requests/minute
Write operations (POST, DELETE)20 requests/minute
Document uploads (POST /shelves)10 requests/hour