A connector is an internal-only FastAPI service. It never authenticates users, never writes to the database and never exposes a public route. core-api calls it with a short-lived JWT and persists what it returns.
Required endpoints
GET /health liveness, no dependencies GET /ready credentials resolve, upstream reachable GET /capabilities list of capability keys POST /v1/sync pull a window; returns normalized objects + cursor POST /v1/backfill explicit ISO-8601 range; idempotent
Required headers and claims
- Authorization: Bearer <internal JWT> with iss=core-api, aud=<connector name>, tenant_id, exp/iat/jti
- X-Request-Id (unique), X-Correlation-Id (stable per sync run or export batch), X-Tenant-Id (must equal the JWT claim)
- Idempotency-Key on every side-effect call
Rules
- Treat tenant_id in the body as informational; validate it against the JWT.
- Redact secrets in logs by default.
- Return structured errors with a retry hint; never partial writes.