Authentication

The API Gateway (api.timepointai.com) is the auth authority for the Timepoint ecosystem. It owns JWT issuance, OAuth provider integration, API key validation, and credit management. Backend services like Flash have auth disabled and trust identity headers from the Gateway.

Auth Schemes

Bearer JWT (End Users)

The Gateway issues JWTs via OAuth sign-in (Apple, Google, GitHub) and demo auth flows. Consumer apps send the JWT as a Bearer token to the Gateway, which validates it and proxies requests to backend services with an X-User-ID header.

curl -X POST https://api.timepointai.com/api/v1/timepoints/generate/sync \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"query": "Moon landing, July 20 1969", "generate_image": true}'

API Keys (External Developers)

API keys are validated by the Gateway. They function like Bearer tokens for programmatic access:

curl https://api.timepointai.com/api/v1/timepoints/generate/sync \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Moon landing, July 20 1969"}'

X-Service-Key (Service-to-Service)

Used for direct service-to-service calls between backend services. Service keys are configured per-service via environment variables.

X-Admin-Key (Admin Operations)

Used for privileged admin operations on backend services. Admin keys are configured per-service via environment variables.

OAuth Providers

The Gateway supports three OAuth providers for end-user authentication:

Provider	Flow	Notes
Apple Sign-In	OAuth 2.0 / OIDC	Primary auth for iOS apps
Google	OAuth 2.0	Web and cross-platform
GitHub	OAuth 2.0	Developer access

All OAuth flows go through the Gateway’s /api/v1/auth/* endpoints, which issue Gateway JWTs upon successful authentication.

Public Access (No Auth)

The Clockchain public API requires no authentication:

curl https://clockchain.timepointai.com/api/v1/stats
curl https://clockchain.timepointai.com/api/v1/moments?limit=10

Gateway Proxy Pattern

When a consumer request hits the Gateway:

Client sends Authorization: Bearer <jwt> to api.timepointai.com
Gateway validates the JWT and extracts the user identity
Gateway proxies the request to the appropriate backend service
Backend services are internal only and not directly accessible to consumers

Gateway-Native Endpoints

These endpoints are handled directly by the Gateway (not proxied to any backend):

Path	Description
`/api/v1/auth/*`	OAuth flows, JWT issuance, token refresh
`/api/v1/users/*`	User profile management
`/api/v1/credits/*`	Credit balance and usage
`/health`	Gateway health check

Getting Access

Service keys are currently available via the developer preview program. Sign up at timepointai.com.

Health Check

All services expose unauthenticated health endpoints:

# API Gateway
curl https://api.timepointai.com/health
# → {"status":"healthy","service":"timepoint-api-gateway","version":"0.1.0"}

# Flash (direct)
curl https://flash.timepointai.com/health
# → {"status":"healthy","database":true,"providers":{"google":true,"openrouter":true,"stability":true}}

# Clockchain (via stats)
curl https://clockchain.timepointai.com/api/v1/stats

Getting Started

Products

API Reference

Authentication

Authentication

Auth Schemes

Bearer JWT (End Users)

API Keys (External Developers)

X-Service-Key (Service-to-Service)

X-Admin-Key (Admin Operations)

OAuth Providers

Public Access (No Auth)

Gateway Proxy Pattern

Gateway-Native Endpoints

Getting Access

Health Check

​Authentication

​Auth Schemes

​Bearer JWT (End Users)

​API Keys (External Developers)

​X-Service-Key (Service-to-Service)

​X-Admin-Key (Admin Operations)

​OAuth Providers

​Public Access (No Auth)

​Gateway Proxy Pattern

​Gateway-Native Endpoints

​Getting Access

​Health Check

Authentication

Auth Schemes

Bearer JWT (End Users)

API Keys (External Developers)

X-Service-Key (Service-to-Service)

X-Admin-Key (Admin Operations)

OAuth Providers

Public Access (No Auth)

Gateway Proxy Pattern

Gateway-Native Endpoints

Getting Access

Health Check