Authentication

Authentication

OstrichDB uses JWT (JSON Web Token) based authentication to secure API access and ensure user isolation. This document explains how authentication works and how to use it.

Overview

The authentication system provides:

• Stateless authentication: JWT tokens contain all necessary information
• User isolation: Each user can only access their own projects
• Secure token handling: Tokens are cryptographically signed
• Configurable expiration: Token lifetime can be customized

JWT Tokens

Token Structure

JWT tokens contain three parts separated by dots:

header.payload.signature

Example token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Token Payload

The JWT payload contains user information:

{
  "sub": "user123",           // User ID (subject)
  "iat": 1516239022,         // Issued at timestamp
  "exp": 1516242622,         // Expiration timestamp
  "iss": "ostrichdb-server"  // Issuer
}

Using Authentication

Including Tokens in Requests

Include the JWT token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Request

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://localhost:8042/api/v1/projects

User Management

User Registration

Create a new user account (typically done during setup):

# This would typically be done through a setup script
# or admin interface, not directly via API

User Login

Authenticate and receive a JWT token:

curl -X POST http://localhost:8042/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username": "your-username", "password": "your-password"}'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "user_id": "user123"
  }
}

Token Management

Token Expiration

Tokens have a configurable expiration time (default: 1 hour):

• Short-lived tokens: More secure, require frequent renewal
• Long-lived tokens: More convenient, higher security risk

Token Refresh

Refresh expired tokens without re-authentication:

curl -X POST http://localhost:8042/api/v1/auth/refresh \
     -H "Authorization: Bearer YOUR_EXPIRED_TOKEN"

Token Validation

The server automatically validates tokens on each request:

1. Signature verification: Ensures token hasn’t been tampered with
2. Expiration check: Rejects expired tokens
3. User validation: Confirms user still exists and is active

Security Best Practices

Token Storage

• Client-side: Store tokens securely (not in localStorage)
• Server-side: Use secure, random JWT secrets
• Transmission: Always use HTTPS in production

Token Handling

• Expiration: Use reasonable expiration times
• Renewal: Implement automatic token refresh
• Revocation: Implement token blacklisting if needed

Error Handling

Handle authentication errors gracefully:

# Invalid token response
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid or expired token"
  }
}

Configuration

JWT Configuration

Configure authentication in your config file:

{
  "security": {
    "jwt_secret": "your-secure-random-secret-key",
    "jwt_expiration": "1h",
    "jwt_issuer": "ostrichdb-server",
    "require_auth": true
  }
}

Security Settings

• jwt_secret: Cryptographic key for signing tokens (keep secret!)
• jwt_expiration: Token lifetime (e.g., “1h”, “24h”, “7d”)
• jwt_issuer: Token issuer identifier
• require_auth: Whether authentication is required for API access

User Isolation

Project Ownership

Each project belongs to a specific user:

• Users can only access their own projects
• Project operations verify ownership
• Cross-user access is prevented

Access Control Flow

1. Request received: API endpoint receives request
2. Token validation: JWT token verified and decoded
3. User identification: User ID extracted from token
4. Resource access: Check if user owns requested resource
5. Operation execution: Proceed if authorized, reject if not

Troubleshooting

Common Issues

Token Missing

Error: AUTHENTICATION_FAILED - No authorization token provided
Solution: Include Authorization header with Bearer token

Token Expired

Error: AUTHENTICATION_FAILED - Token has expired
Solution: Refresh token or re-authenticate

Invalid Token

Error: AUTHENTICATION_FAILED - Invalid token signature
Solution: Check token format and server JWT secret

Access Denied

Error: AUTHORIZATION_FAILED - Insufficient permissions
Solution: Verify you own the requested resource

Debug Authentication Issues

Check token validity:

# Decode JWT token (header and payload only)
echo "YOUR_TOKEN" | cut -d. -f2 | base64 -d | jq .

Verify server configuration:

# Check server logs for authentication errors
tail -f /path/to/ostrichdb.log | grep -i auth

Next Steps

Learn about other security features:

• Encryption - Data encryption and key management
• Access Control - Fine-grained permission system
• Configuration - Security configuration options