> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timepointai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Timepoint APIs.

# 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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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):

| 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](https://timepointai.com).

## Health Check

All services expose unauthenticated health endpoints:

```bash theme={null}
# 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
```