Authentication

Authentication Methods

LiveFolio supports two authentication methods for the REST API:

Method	Use case	Header
API Key (Bearer)	CI/CD, custom integrations, scripts	Authorization: Bearer lf_live_...
OAuth 2.0	Third-party apps acting on behalf of users	Authorization: Bearer <access_token>

API Keys

API keys are scoped to a workspace (organization). All key-based requests operate within that workspace's context.

Key format: lf_live_ followed by 48 hex characters (cryptographically random).

Get Your API Key

1. Go to Settings → API Keys in the LiveFolio dashboard
2. Copy the existing key or click Generate New Key to rotate

Managing Keys via API

List current key:

curl https://livefolio.cloud/api/keys \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx"

Response:

{
  "apiKey": "lf_live_a1b2c3d4e5f6..."
}

Generate (rotate) a new key:

curl -X POST https://livefolio.cloud/api/keys \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx"

Requires Owner or Admin role. Rotating a key immediately invalidates the previous one.

Response:

{
  "apiKey": "lf_live_f6e5d4c3b2a1..."
}

Revoke a key:

curl -X DELETE https://livefolio.cloud/api/keys \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx"

Requires Owner or Admin role. After revocation, no API key is active until a new one is generated.

Response:

{
  "success": true
}

OAuth 2.0

For third-party applications that need to act on behalf of LiveFolio users, use the OAuth 2.0 authorization code flow.

Endpoint	Description
POST /api/oauth/register	Register an OAuth client application
GET /api/oauth/authorize	Start the authorization code flow
POST /api/oauth/token	Exchange authorization code for access token
POST /api/oauth/revoke	Revoke an access token

OAuth tokens are passed the same way as API keys:

Authorization: Bearer <oauth_access_token>

Using Authentication in Requests

All authenticated endpoints require the Authorization header:

curl https://livefolio.cloud/api/files \
  -H "Authorization: Bearer lf_live_xxxxxxxxxxxx"

OSS Mode

In OSS (self-hosted) mode, authentication is optional. If LiveFolio_API_KEY is set in the environment, the sync endpoint requires it. Other endpoints are unauthenticated by default.

Rate Limits

Authenticated requests include rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Example:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1718400000

Rate limits vary by plan tier. Public endpoints (comments, reactions, analytics) have separate, higher limits.

Handling Rate Limits

When you hit a rate limit, the API returns 429 Too Many Requests. Implement exponential backoff:

async function apiCall(url, options, retries = 3) {
  const response = await fetch(url, options);
  if (response.status === 429 && retries > 0) {
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0') * 1000;
    const waitMs = Math.max(resetTime - Date.now(), 1000);
    await new Promise(r => setTimeout(r, waitMs));
    return apiCall(url, options, retries - 1);
  }
  return response;
}