Documentation Index
Fetch the complete documentation index at: https://mintlify.com/timepoint-ai/timepoint-clockchain/llms.txt
Use this file to discover all available pages before exploring further.
Service Key Authentication
All API endpoints (except/ and /health) require authentication using a service key passed via the X-Service-Key header.
Required Header
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
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 theX-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 avisibility 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)
Error Responses
Invalid Service Key
403 Forbidden
Service Key Not Configured
503 Service Unavailable
This error occurs when the server’s
SERVICE_API_KEY environment variable is not set.Unauthorized Moment Access
404 Not Found
Admin Authentication
Some endpoints (like/bulk-generate) require an additional admin key:
Admin key for privileged operations
ADMIN_KEY configuration value and will return 403 Forbidden if the key is invalid or missing.
Best Practices
- Keep keys secure - Never commit service keys to version control
- Use environment variables - Store keys in environment variables or secret management systems
- Rotate keys regularly - Update service keys periodically for security
- Use HTTPS - Always make requests over HTTPS to prevent key interception
- 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