Authentication

Set up and use authentication with Dakora

Overview

Dakora supports multiple authentication methods to protect your API endpoints and manage access control:

1. API Key Authentication — for programmatic access and integrations (recommended for server‑to‑server)
2. JWT Authentication (Clerk) — for browser and user‑initiated flows
3. Development Mode — no authentication (local development only)

Priority order per request:

1. API Key via X-API-Key
2. JWT Bearer via Authorization: Bearer <token>
3. No‑auth (only when AUTH_REQUIRED=false)

Authentication Modes

Production Mode (Auth Enabled)

When AUTH_REQUIRED=true:

• All API endpoints require valid auth
• Multi‑tenant scoping applies (user/workspace/project)
• Unauthorized requests return 401/403

Development Mode (No Auth)

When AUTH_REQUIRED=false:

• Endpoints are public (no headers required)
• Intended for local development only
• Requests are scoped to a default project

Frontend Setup (Clerk JWT)

Create studio/.env.local:

# Enable authentication
VITE_AUTH_REQUIRED=true

# Clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_test_YOUR_KEY_HERE

# API
VITE_API_URL=http://localhost:8000

Run the frontend:

cd studio
npm install
npm run dev

Backend Setup

Set environment variables in your backend .env or deployment:

# Enable authentication
AUTH_REQUIRED=true

# Clerk JWT verification
CLERK_JWT_ISSUER=https://YOUR-CLERK-DOMAIN.clerk.accounts.prod.liveblocks.io
CLERK_JWKS_URL=https://YOUR-CLERK-DOMAIN.clerk.accounts.prod.liveblocks.io/.well-known/jwks.json

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dakora

API Key Authentication (Project‑Scoped)

Generate API Keys

Web App

Use Settings → API Keys to create a project API key. Keys are shown once; copy and store securely.

Use API Keys

First, resolve your default project with your API key:

curl

curl -s http://localhost:8000/api/me/context \
  -H "X-API-Key: dkr_..."

Call project‑scoped endpoints with project_id:

curl -s "http://localhost:8000/api/projects/$PROJECT_ID/prompts" \
  -H "X-API-Key: dkr_..."

Manage API Keys (CRUD)

# Create
curl -s -X POST "http://localhost:8000/api/projects/$PROJECT_ID/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Prod Key", "expires_in_days": 365}'

# List (X-API-Key or JWT)
curl -s "http://localhost:8000/api/projects/$PROJECT_ID/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Get by ID
curl -s "http://localhost:8000/api/projects/$PROJECT_ID/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Revoke
curl -s -X DELETE "http://localhost:8000/api/projects/$PROJECT_ID/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

API Key Best Practices

Store Keys Securely

Never commit API keys to version control. Use environment variables:

DAKORA_API_KEY=your-api-key

Access in code:

import os
api_key = os.environ.get("DAKORA_API_KEY")

Rotate Keys Regularly

Generate new keys periodically and revoke old ones to maintain security.

Use Separate Keys

Create different API keys for different services or environments (dev, staging, production).

Monitor Usage

Track which API keys are being used and when. Disable unused keys.

Scope to Projects

Limit API keys to specific projects when possible to reduce blast radius if compromised.

JWT Authentication (Clerk)

How It Works

1. User Signs In - User authenticates with Clerk
2. JWT Generated - Clerk issues a JWT token
3. Token Sent - Frontend adds token to request headers
4. Token Verified - Backend verifies JWT signature with Clerk’s public key
5. Request Processed - If valid, request is processed with user context

Making Authenticated Requests

The frontend automatically handles JWT injection via the createApiClient() function:

import { createApiClient } from '@/utils/api';

// With authentication
const client = await createApiClient();

// Automatically includes: Authorization: Bearer <token>
const templates = await client.get('/api/templates');

Session Persistence

Clerk SDK automatically handles session persistence:

• Tokens stored securely in localStorage
• Tokens refreshed before expiration
• Session restored on page reload
• Works across browser tabs

Error Handling

401 Unauthorized

{
  "detail": "Unauthorized - No valid authentication provided"
}

Solutions:

• Verify your API key is correct (if using API key auth)
• Check that your JWT token hasn’t expired (if using Clerk)
• Ensure X-API-Key or Authorization header is set
• Verify AUTH_REQUIRED is true in backend configuration

403 Forbidden

{
  "detail": "Forbidden - User does not have access to this resource"
}

Solutions:

• Verify you have access to the project
• Check that the resource belongs to your project scope
• Ensure your user role has appropriate permissions

Multi-Tenancy & Scoping

When authentication is enabled, requests are scoped by:

• User ID - From JWT token (Clerk) or API key owner
• Project ID - Stored with user or API key

This means:

• Users only see their own templates and resources
• Projects are isolated by default
• Cross-tenant access is prevented automatically

Example:

# Storage is automatically scoped
storage_prefix = f"users/{user_id}/projects/{project_id}"
# Templates stored at: users/user123/projects/proj456/templates/...

Testing with Authentication

Using TestClient (Backend)

from fastapi.testclient import TestClient
from dakora_server.main import app

client = TestClient(app)

# With API Key
headers = {"X-API-Key": "test-key"}
response = client.get("/api/templates", headers=headers)
assert response.status_code == 200

# With JWT Token
headers = {"Authorization": "Bearer <token>"}
response = client.get("/api/templates", headers=headers)
assert response.status_code == 200

# Without auth (should fail if AUTH_REQUIRED=true)
response = client.get("/api/templates")
assert response.status_code == 401

Using cURL (Manual)

# Health check (public)
curl http://localhost:8000/api/health

# Resolve project
curl -H "X-API-Key: dkr_..." http://localhost:8000/api/me/context

# List prompts (project‑scoped)
curl -H "X-API-Key: dkr_..." "http://localhost:8000/api/projects/$PROJECT_ID/prompts"

# Invalid key
curl -H "X-API-Key: invalid" http://localhost:8000/api/me/context
# → 401 Unauthorized

Troubleshooting

Frontend shows 'Authenticate' but no sign-in modal

Issue: Clerk not configured properly

Solution:

1. Verify VITE_CLERK_PUBLISHABLE_KEY is set in studio/.env.local
2. Ensure key is correct (check Clerk dashboard)
3. Restart dev server: npm run dev

API requests return 401 Unauthorized

Issue: Authentication failed

Solutions:

• Check X-API-Key is set correctly (if using API key)
• Verify JWT token hasn’t expired (if using Clerk)
• Ensure AUTH_REQUIRED=true in backend config
• Check browser console for token errors

Can't access own templates after login

Issue: Multi-tenancy scoping issue

Solution:

• Verify database stores templates under user scope
• Check user ID matches between frontend and backend
• Ensure project ID is properly set in Clerk custom claims

Backend doesn't validate Clerk tokens

Issue: CLERK_JWT_ISSUER or CLERK_JWKS_URL not set

Solution:

1. Get values from Clerk dashboard
2. Set in backend .env
3. Restart backend server

Next Steps

API Keys Guide

Detailed API key management

Getting Started

Make your first API calls