Skip to main content

Authentication

Friday Dev supports multiple authentication methods for API access.

Authentication Methods​

Simple bearer token authentication:

Authorization: Bearer YOUR_API_KEY

2. Session Token​

For browser-based applications:

Cookie: friday_session=SESSION_TOKEN

3. OAuth (Coming Soon)​

GitHub and Google OAuth for team features.

API Keys​

Generate API Key​

# Generate new key
friday-dev config set apiKey $(openssl rand -hex 32)

# View current key
friday-dev config get apiKey

Or via the UI:

  1. Go to Settings
  2. Click "API Keys"
  3. Click "Generate New Key"
  4. Copy and save the key

Using API Keys​

HTTP Header:

GET /api/tasks HTTP/1.1
Host: localhost:3000
Authorization: Bearer your-api-key-here

cURL:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/tasks

JavaScript:

fetch('/api/tasks', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

Python:

import requests

response = requests.get(
    'http://localhost:3000/api/tasks',
    headers={'Authorization': f'Bearer {api_key}'}
)

Key Security​

  • Never commit API keys to version control
  • Use environment variables: 
    export FRIDAY_DEV_API_KEY="your-key"
  • Rotate keys periodically
  • Limit scope when possible

Session Authentication​

For web applications using cookies:

Login​

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "User Name"
  },
  "session": {
    "token": "session_xyz",
    "expires_at": "2024-02-15T00:00:00Z"
  }
}

The session token is also set as an HTTP-only cookie.

Logout​

POST /api/auth/logout
Cookie: friday_session=SESSION_TOKEN

Session Refresh​

Sessions expire after 7 days. Refresh before expiry:

POST /api/auth/refresh
Cookie: friday_session=SESSION_TOKEN

JWT Tokens​

For stateless authentication:

Get Token​

POST /api/auth/token
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using JWT​

Authorization: Bearer eyJhbGciOiJIUzI1...

Token Structure​

{
  "sub": "user_123",
  "iat": 1705334400,
  "exp": 1705338000,
  "scope": ["tasks:read", "tasks:write", "agents:run"]
}

Scopes & Permissions​

API keys and tokens can have limited scopes:

ScopeDescription
tasks:readRead tasks
tasks:writeCreate/update/delete tasks
projects:readRead projects
projects:writeManage projects
agents:runRun AI agents
adminFull access

Scoped API Key​

Create a key with limited permissions:

friday-dev apikey create --scopes tasks:read,tasks:write

OAuth Integration​

GitHub OAuth​

Coming in a future release:

GET /api/auth/oauth/github

Redirects to GitHub for authorization.

Google OAuth​

GET /api/auth/oauth/google

Error Responses​

401 Unauthorized​

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

Causes:

  • Missing Authorization header
  • Invalid API key
  • Expired token/session

403 Forbidden​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this action"
  }
}

Causes:

  • API key lacks required scope
  • User doesn't have permission
  • Resource belongs to another user

Security Best Practices​

1. Use HTTPS​

Always use HTTPS in production:

https://your-domain.com/api

2. Store Keys Securely​

// Bad - hardcoded
const apiKey = 'sk_live_abc123';

// Good - environment variable
const apiKey = process.env.FRIDAY_DEV_API_KEY;

3. Rotate Keys Regularly​

# Generate new key
friday-dev apikey rotate

# Revoke old key
friday-dev apikey revoke OLD_KEY_ID

4. Use Minimal Scopes​

Request only the permissions you need:

// Only needs to read tasks
const apiKey = generateKey({ scopes: ['tasks:read'] });

5. Monitor Usage​

Check API key usage in settings:

friday-dev apikey usage

Rate Limiting​

Authentication affects rate limits:

Auth TypeLimit
No auth10 req/min
API Key1000 req/min
OAuth1000 req/min

Headers in response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705334400

Testing Authentication​

Verify API Key​

curl -I -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/auth/verify

Response:

HTTP/1.1 200 OK
X-User-Id: user_123
X-Scopes: tasks:read,tasks:write

Debug Mode​

Enable auth debugging:

RUST_LOG=friday_dev::auth=debug friday-dev

Next Steps​