Authentication

Secure your API requests with JWT tokens, API keys, and OAuth2 authentication.

Overview

The Sapphire Legal AI API supports multiple authentication methods to secure your requests and control access to your data and resources.

Authentication methods

JWT (JSON Web Tokens)

JWT tokens are the primary authentication method for user-based API access. They provide secure, stateless authentication with built-in expiration.

Getting a JWT token

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

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

Using JWT tokens

GET /api/cases
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

API Keys

API keys provide long-term access for service-to-service communication and integrations. They're ideal for automated systems and background processes.

Generating API keys

POST /api/admin/api-keys
Authorization: Bearer <admin_jwt_token>
Content-Type: application/json

{
  "name": "Integration API Key",
  "permissions": ["read:cases", "write:documents"],
  "expires_at": "2025-12-31T23:59:59Z"
}

Using API keys

GET /api/cases
X-API-Key: sk_live_1234567890abcdef...
Content-Type: application/json

OAuth2 (Enterprise)

OAuth2 provides enterprise-grade authentication for organizations using SSO systems like Azure AD, Okta, or custom identity providers.

OAuth2 flow

1. Redirect users to authorization endpoint
2. User authenticates with identity provider
3. Receive authorization code
4. Exchange code for access token
5. Use access token for API requests

Security best practices

Token management

• Store securely: Never hardcode tokens in source code
• Rotate regularly: Update API keys and refresh JWT tokens
• Monitor usage: Track token usage for security anomalies
• Scope permissions: Use minimal required permissions
• Expire tokens: Set appropriate expiration times

Request security

• Use HTTPS: Always make requests over secure connections
• Validate responses: Verify response authenticity
• Handle errors: Implement proper error handling
• Rate limiting: Respect API rate limits
• Logging: Log authentication events for audit

Error handling

Common authentication errors

Error response format

{
  "error": "unauthorized",
  "error_description": "Invalid or expired token",
  "error_code": "AUTH_001",
  "timestamp": "2025-01-20T10:30:00Z",
  "request_id": "req_1234567890abcdef"
}

Code examples

cURL examples

JWT Authentication

# Login to get JWT token
curl -X POST https://api.sapphirelegal.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

# Use JWT token for API request
curl -X GET https://api.sapphirelegal.ai/api/cases \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json"

API Key Authentication

# API request with API key
curl -X GET https://api.sapphirelegal.ai/api/cases \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json"

JavaScript examples

Fetch API with JWT

// Login and get token
const loginResponse = await fetch('https://api.sapphirelegal.ai/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});

const { token } = await loginResponse.json();

// Use token for API request
const casesResponse = await fetch('https://api.sapphirelegal.ai/api/cases', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const cases = await casesResponse.json();

Fetch API with API Key

const response = await fetch('https://api.sapphirelegal.ai/api/cases', {
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  }
});

const cases = await response.json();

What's next

• API Endpoints - Explore available API endpoints and methods
• Webhooks - Set up event-driven notifications
• SDKs & Libraries - Use official client libraries