Skip to main content

​
API Gateway

The API Gateway at api.timepointai.com is the primary entry point for all client traffic. It handles authentication, authorization, credit management, rate limiting, and proxies requests to downstream services.
Consumer apps (iPhone, web app, external clients) should always use api.timepointai.com. The gateway authenticates and routes transparently — downstream services like Flash never see raw credentials.

​
Auth Endpoints

All auth endpoints are at https://api.timepointai.com/api/v1/auth/.
MethodPathDescriptionAuth
POST/auth/appleApple Sign-InNone (public)
POST/auth/googleGoogle Sign-InNone (public)
POST/auth/githubGitHub OAuthNone (public)
POST/auth/demoDemo login (App Store review)None (public)
POST/auth/refreshRefresh JWT token pairRefresh token
POST/auth/logoutRevoke refresh tokenBearer JWT
GET/auth/meGet current user profileBearer JWT
DELETE/auth/meDelete account and all dataBearer JWT
POST/auth/dev/tokenIssue dev tokenX-Admin-Key
POST/auth/service-tokenIssue service tokenX-Admin-Key

​
User Endpoints

MethodPathDescriptionAuth
POST/users/resolveFind or create user by external IDX-Service-Key
GET/users/me/timepointsList user’s timepoints (proxied to Flash)Bearer JWT
GET/users/me/exportExport user dataBearer JWT

​
Credit Endpoints

MethodPathDescriptionAuth
GET/credits/balanceGet credit balanceBearer JWT
GET/credits/historyGet transaction historyBearer JWT
GET/credits/costsGet operation costsNone (public)
POST/credits/admin/grantAdmin credit grantX-Admin-Key

​
Proxy Routes

The gateway proxies requests to downstream services based on URL pattern:
PatternDestination
/api/v1/timepoints/*Flash
/api/v1/clockchain/*Clockchain
/api/v1/billing/*Billing
Backend services are internal only and accessed exclusively through the gateway. Never call backend services directly from untrusted clients.

​
Authentication Flow

1. Client → POST /api/v1/auth/{provider}   (Apple, Google, GitHub)
2. Gateway validates identity → issues JWT access token + refresh token
3. Client → sends Authorization: Bearer <token> on subsequent requests
4. Gateway validates JWT → resolves user → checks credits
5. Gateway proxies request to downstream service with X-User-ID header
6. Downstream service trusts X-User-ID (no re-authentication)

​
Example: Authenticate and Render

# 1. Authenticate (Apple Sign-In)
curl -X POST https://api.timepointai.com/api/v1/auth/apple \
  -H "Content-Type: application/json" \
  -d '{"identity_token": "APPLE_ID_TOKEN"}'

# Response: { "access_token": "eyJ...", "refresh_token": "..." }

# 2. Render a moment (proxied to Flash)
curl -X POST https://api.timepointai.com/api/v1/timepoints/generate/sync \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ..." \
  -d '{"query": "Moon landing, July 20 1969", "generate_image": true}'

# 3. Check credit balance
curl https://api.timepointai.com/api/v1/credits/balance \
  -H "Authorization: Bearer eyJ..."

​
Rate Limits

TierRequests/minDaily limit
Free10100
Pro601,000
Enterprise30010,000
Rate limit headers are included on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

​
Health Check

GET /health
No auth required. Returns gateway status. 
{
  "status": "healthy",
  "version": "1.0.0"
}