Skip to main content

​
OAuth Connections

Users on the Connect plan can link their OpenAI account to run compile interviews using their own API subscription, bypassing system credits.

​
List connected providers

curl https://api.faces.sh/v1/oauth \
  -H "Authorization: Bearer YOUR_KEY"

[
  {
    "provider": "openai",
    "connected": true,
    "connected_at": "2026-03-15T10:30:00Z"
  }
]

​
Connect OpenAI

The OAuth flow uses a browser redirect. First, get the authorization URL: 
curl https://api.faces.sh/v1/oauth/openai/authorize \
  -H "Authorization: Bearer YOUR_KEY"

{
  "authorize_url": "https://chatgpt.com/authorize?client_id=...&redirect_uri=..."
}
Open authorize_url in a browser. After approving, you’ll be redirected back with an authorization code. The callback endpoint handles the token exchange automatically.
OAuth is only available on the Connect plan. Free and Standard plan users will receive 403 Forbidden.

​
Disconnect a provider

curl -X DELETE https://api.faces.sh/v1/oauth/openai \
  -H "Authorization: Bearer YOUR_KEY"

{
  "detail": "Disconnected openai"
}

​
How OAuth affects billing

When an OAuth connection is active, compile interviews automatically use your connected account instead of system credits. The billing priority is:
  1. OAuth (Connect plan with active connection) — uses your OpenAI subscription
  2. Compile quota (Standard/Pro plans) — uses included monthly tokens
  3. API credits — pay-per-use from your credit balance
You can override this by passing interviewer_billing_source when starting a compile thread: 
curl -X POST https://api.faces.sh/v1/compile/threads \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "alice",
    "label": "Interview",
    "interviewer_billing_source": "credits"
  }'
Valid values: "oauth", "compile", "credits".