Skip to main content

Service Key Authentication

All API endpoints (except / and /health) require authentication using a service key passed via the X-Service-Key header.

Required Header

string
required
Your service API key for authenticating requests

Example Request

How Authentication Works

The API uses a secure constant-time comparison to verify service keys. Here’s the authentication logic from the source code:
The authentication uses hmac.compare_digest() to prevent timing attacks when comparing the service key.

User Identification

For user-specific operations, you can optionally include a user ID in your requests.

Optional User Header

string
Optional user identifier for user-scoped operations

User ID Extraction

The API extracts the user ID from the header as follows:

When to Use User ID

Include the X-User-Id header when:
  • Accessing private moments created by a specific user
  • Generating new moments attributed to a user
  • Publishing moments on behalf of a user

Example with User ID

Visibility and User Access

Moments have a visibility property that controls access:
  • public - Accessible by anyone with a valid service key
  • private - Only accessible by the user who created it (requires matching X-User-Id)
Private moments return a 404 Not Found error if accessed without the correct X-User-Id header, even with a valid service key.

Error Responses

Invalid Service Key

Status Code: 403 Forbidden

Service Key Not Configured

Status Code: 503 Service Unavailable
This error occurs when the server’s SERVICE_API_KEY environment variable is not set.

Unauthorized Moment Access

Status Code: 404 Not Found
This response is returned both for truly non-existent moments and for private moments that you don’t have access to, preventing information disclosure.

Admin Authentication

Some endpoints (like /bulk-generate) require an additional admin key:
string
Admin key for privileged operations
Admin operations use a separate ADMIN_KEY configuration value and will return 403 Forbidden if the key is invalid or missing.

Best Practices

  1. Keep keys secure - Never commit service keys to version control
  2. Use environment variables - Store keys in environment variables or secret management systems
  3. Rotate keys regularly - Update service keys periodically for security
  4. Use HTTPS - Always make requests over HTTPS to prevent key interception
  5. Handle 403 errors - Implement proper error handling for authentication failures

Next Steps

API Overview

Browse all available API endpoints

Moments API

Learn how to retrieve and search moments