---
title: 'Authentication Guide'
description:
  'Complete guide to authenticating with the Lilith Wisdom Platform API'
layout: 'guide'
category: 'authentication'
tags: ['auth', 'jwt', 'tokens', 'security']
---

# Authentication Guide

## Overview

The Lilith Wisdom Platform API uses JSON Web Tokens (JWT) for authentication.
All API requests (except public endpoints) must include a valid JWT token in the
Authorization header.

## Authentication Methods

We support multiple authentication methods depending on your use case:

- **Client Credentials** - For server-to-server communication
- **Authorization Code** - For web applications with user login
- **API Keys** - For simple integration scenarios
- **Biometric Authentication** - For mobile applications

## Getting Started

### 1. Create Developer Account

First, create a developer account at
[https://portal.lilith.ai](https://portal.lilith.ai):

1. Visit the developer portal
2. Click "Sign Up"
3. Complete the registration form
4. Verify your email address
5. Set up two-factor authentication

### 2. Generate API Credentials

1. Log in to your developer dashboard
2. Navigate to **API Keys** → **Create New Key**
3. Select the appropriate key type:
   - **Production**: For live applications
   - **Staging**: For testing and development
4. Configure permissions and rate limits
5. Copy your client ID and client secret

### 3. Choose Authentication Method

Based on your application type, choose the appropriate authentication method:

- **Web Applications**: Authorization Code Flow
- **Mobile Apps**: Authorization Code Flow with PKCE
- **Server-to-Server**: Client Credentials Flow
- **Simple Scripts**: API Key Authentication

## Client Credentials Flow

Use this method for server-to-server communication where no user interaction is
required.

### Step 1: Request Access Token

```bash
curl -X POST https://api.lilith.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "api:read api:write"
  }'
```

### Step 2: Handle Response

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api:read api:write",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Step 3: Use Access Token

```bash
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://api.lilith.ai/v1/users/me
```

## Authorization Code Flow

Use this method for web and mobile applications with user login.

### Step 1: Redirect User to Authorization

```javascript
const authUrl =
  `https://auth.lilith.ai/oauth/authorize?` +
  `response_type=code&` +
  `client_id=${encodeURIComponent(clientId)}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `scope=${encodeURIComponent('api:read api:write')}&` +
  `state=${encodeURIComponent(generateState())}`;

window.location.href = authUrl;
```

### Step 2: Handle Authorization Callback

```javascript
// In your callback handler
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const state = urlParams.get('state');

// Verify state to prevent CSRF
if (state !== storedState) {
  throw new Error('Invalid state parameter');
}

// Exchange code for tokens
exchangeCodeForTokens(code);
```

### Step 3: Exchange Code for Tokens

```bash
curl -X POST https://auth.lilith.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "code": "authorization_code_from_callback",
    "redirect_uri": "https://your-app.com/callback",
    "code_verifier": "code_verifier_from_pkce"
  }'
```

## API Key Authentication

For simple integration scenarios, you can use API key authentication.

### Using API Key in Header

```bash
curl -H "X-API-Key: your_api_key" \
     https://api.lilith.ai/v1/content/meditations
```

### Using API Key as Query Parameter

```bash
curl "https://api.lilith.ai/v1/content/meditations?api_key=your_api_key"
```

## Token Management

### Token Storage

Store tokens securely:

- **Server-side**: Use environment variables or secure key management
- **Client-side**: Use httpOnly cookies or secure storage
- **Mobile**: Use platform secure storage (Keychain, Keystore)

### Token Refresh

Access tokens expire after 1 hour. Use the refresh token to obtain a new token:

```bash
curl -X POST https://api.lilith.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "your_refresh_token",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'
```

### Token Revocation

Revoke tokens when no longer needed:

```bash
curl -X POST https://api.lilith.ai/v1/auth/revoke \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "token": "token_to_revoke",
    "token_type_hint": "access_token"
  }'
```

## SDK Integration

### TypeScript/JavaScript

```typescript
import { LilithAPIClient } from '@lilith/sdk';

const client = new LilithAPIClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  baseURL: 'https://api.lilith.ai',
});

// Client handles token management automatically
const user = await client.users.getCurrentUser();
```

## Error Handling

### Common Authentication Errors

| Error                | Description                                 | Solution                           |
| -------------------- | ------------------------------------------- | ---------------------------------- |
| `invalid_client`     | Invalid client credentials                  | Verify client ID and secret        |
| `invalid_grant`      | Invalid authorization code or refresh token | Request new authorization          |
| `expired_token`      | Access token has expired                    | Use refresh token to get new token |
| `insufficient_scope` | Token lacks required permissions            | Request appropriate scopes         |

### Handling Token Expiration

```typescript
async function makeApiRequest(url: string, options: RequestOptions) {
  try {
    const response = await fetch(url, options);

    if (response.status === 401) {
      // Token expired, try to refresh
      await refreshAccessToken();
      // Retry request with new token
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          Authorization: `Bearer ${getNewAccessToken()}`,
        },
      });
    }

    return response;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}
```

## Security Best Practices

### 1. Protect Credentials

- Never expose client secrets in client-side code
- Use environment variables for sensitive configuration
- Implement proper secrets management in production

### 2. Use HTTPS

Always use HTTPS for API requests to prevent token interception:

```typescript
// ✅ Good
const baseURL = 'https://api.lilith.ai';

// ❌ Bad
const baseURL = 'http://api.lilith.ai';
```

### 3. Validate Tokens

Always validate JWT tokens before accepting them:

```typescript
import jwt from 'jsonwebtoken';

function validateToken(token: string): boolean {
  try {
    const decoded = jwt.verify(token, publicKey);
    return decoded.exp > Date.now() / 1000;
  } catch (error) {
    return false;
  }
}
```

### 4. Implement Rate Limiting

Respect rate limits and implement backoff strategies:

```typescript
class RateLimitedClient {
  private lastRequest = 0;
  private minInterval = 100; // 100ms between requests

  async makeRequest(url: string, options: RequestOptions) {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;

    if (timeSinceLastRequest < this.minInterval) {
      await new Promise((resolve) =>
        setTimeout(resolve, this.minInterval - timeSinceLastRequest)
      );
    }

    this.lastRequest = Date.now();
    return fetch(url, options);
  }
}
```

### 5. Scope Limitation

Request only the permissions your application needs:

```typescript
// ✅ Good - Specific scopes
const scopes = ['meditations:read', 'users:write'];

// ❌ Bad - Overly broad permissions
const scopes = ['api:*'];
```

## Biometric Authentication

For mobile applications, we support biometric authentication for enhanced
security. The React Native mobile app uses `react-native-biometrics` for
cross-platform biometric authentication on iOS and Android.

## Testing Authentication

### Test Credentials

Use the following test credentials for development:

- **Client ID**: `test_client_id`
- **Client Secret**: `test_client_secret`
- **Test User**: `test@example.com` / `password123`

### Mock Authentication

For testing, you can mock the authentication flow:

```typescript
class MockAuthService implements AuthService {
  async authenticate(): Promise<AuthResult> {
    return {
      accessToken: 'mock_access_token',
      refreshToken: 'mock_refresh_token',
      expiresIn: 3600,
    };
  }
}
```

## Troubleshooting

### Common Issues

**Q: I'm getting "invalid_client" errors** A: Verify your client ID and secret
are correct and haven't expired

**Q: My refresh token isn't working** A: Refresh tokens expire after 30 days.
Request a new authorization

**Q: CORS errors when making requests** A: Ensure your redirect URI is
registered in the developer portal

**Q: Rate limit exceeded** A: Implement proper backoff strategies and respect
rate limits

### Debug Mode

Enable debug mode for additional logging:

```typescript
const client = new LilithAPIClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  debug: true, // Enables verbose logging
});
```

## Support

If you encounter authentication issues:

1. Check the [status page](https://status.lilith.ai) for service availability
2. Review our [API documentation](https://docs.lilith.ai)
3. Contact support at auth-support@lilith.ai
4. Open an issue on
   [GitHub](https://github.com/lilith-ai/lilith-platform/issues)

---

Next: [Explore API Reference](/reference) →
