Skip to main content

​
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:
ProviderFlowNotes
Apple Sign-InOAuth 2.0 / OIDCPrimary auth for iOS apps
GoogleOAuth 2.0Web and cross-platform
GitHubOAuth 2.0Developer 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:
  1. Client sends Authorization: Bearer <jwt> to api.timepointai.com
  2. Gateway validates the JWT and extracts the user identity
  3. Gateway proxies the request to the appropriate backend service
  4. 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):
PathDescription
/api/v1/auth/*OAuth flows, JWT issuance, token refresh
/api/v1/users/*User profile management
/api/v1/credits/*Credit balance and usage
/healthGateway 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}}

# Pro Cloud
curl https://pro.timepointai.com/health
# → {"status":"healthy","service":"timepoint-pro-cloud","version":"0.1.0"}

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