OAuth & Social Login

Let users sign in with their existing accounts from Google, Apple, Facebook, GitHub, and Microsoft. Zyphr handles the entire OAuth flow — provider configuration, token exchange, and connection management.

OAuth Flow

1. Your app requests authorize URL  ──▶  Zyphr API
2. Zyphr returns provider URL       ◀──  redirect user there
3. User authenticates with provider  ──▶  Provider (Google, etc.)
4. Provider redirects to callback    ──▶  Your App (with code + state)
5. Your app sends callback to Zyphr  ──▶  Zyphr API exchanges tokens
6. Zyphr returns user + auth tokens  ◀──  User is logged in

Supported Providers

Provider	Type Value
Google	google
Apple	apple
Facebook	facebook
GitHub	github
Microsoft	microsoft

List Available Providers

Get the list of OAuth providers configured for your application:

curl https://api.zyphr.dev/v1/auth/oauth/providers \
  -H "X-Application-Key: za_pub_xxxx"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/auth/oauth/providers', {
  headers: {
    'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
  },
});

info

Only requires the public key — safe for client-side use. Returns only providers that have been configured in your application settings.

Get Authorization URL

Get the OAuth authorization URL for a specific provider:

curl "https://api.zyphr.dev/v1/auth/oauth/google/authorize?redirect_uri=https://myapp.com/auth/callback" \
  -H "X-Application-Key: za_pub_xxxx"

Node.js

const response = await fetch(
  `https://api.zyphr.dev/v1/auth/oauth/google/authorize?redirect_uri=${encodeURIComponent('https://myapp.com/auth/callback')}`,
  {
    headers: {
      'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
    },
  }
);
const { data } = await response.json();
// data.authorization_url — redirect the user here
// data.state — CSRF state parameter (validated on callback)

Parameters (Query String)

Parameter	Type	Required	Description
redirect_uri	string	Yes	Must match one of your application's configured redirect_uris

Response

{
  "data": {
    "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...",
    "state": "random_csrf_state",
    "provider": "google"
  }
}

Redirect the user to the authorization_url. After they authenticate, the provider redirects back to your redirect_uri with code and state query parameters.

Handle OAuth Callback

After the provider redirects the user back to your app, send the code and state to Zyphr:

curl -X POST https://api.zyphr.dev/v1/auth/oauth/google/callback \
  -H "X-Application-Key: za_pub_xxxx" \
  -H "X-Application-Secret: za_sec_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "4/0AX4XfWh...",
    "state": "random_csrf_state",
    "redirect_uri": "https://myapp.com/auth/callback"
  }'

Node.js

const response = await fetch('https://api.zyphr.dev/v1/auth/oauth/google/callback', {
  method: 'POST',
  headers: {
    'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
    'X-Application-Secret': process.env.ZYPHR_APP_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: oauthCode,
    state: oauthState,
    redirect_uri: 'https://myapp.com/auth/callback',
  }),
});

Parameters

Parameter	Type	Required	Description
code	string	Yes	Authorization code from the provider callback
state	string	Yes	CSRF state from the authorize response
redirect_uri	string	Yes	Must match the redirect_uri used in the authorize step

Response

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "avatar_url": "https://lh3.googleusercontent.com/...",
      "email_verified": true
    },
    "tokens": {
      "access_token": "eyJhbGci...",
      "refresh_token": "zrt_xxxx",
      "expires_in": 3600,
      "token_type": "Bearer"
    },
    "is_new_user": true,
    "provider": "google"
  }
}

If the email matches an existing user, the OAuth connection is linked to that account. Otherwise, a new user is created.

Connection Management

List User's OAuth Connections

Requires the user's access token:

curl https://api.zyphr.dev/v1/auth/oauth/connections \
  -H "X-Application-Key: za_pub_xxxx" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/auth/oauth/connections', {
  headers: {
    'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
    'Authorization': `Bearer ${accessToken}`,
  },
});

Get Connection Details

Get details for a specific provider connection:

curl https://api.zyphr.dev/v1/auth/oauth/connections/google \
  -H "X-Application-Key: za_pub_xxxx" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/auth/oauth/connections/google', {
  headers: {
    'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
    'Authorization': `Bearer ${accessToken}`,
  },
});

Disconnect Provider

Remove an OAuth connection:

curl -X DELETE https://api.zyphr.dev/v1/auth/oauth/google \
  -H "X-Application-Key: za_pub_xxxx" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/auth/oauth/google', {
  method: 'DELETE',
  headers: {
    'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
    'Authorization': `Bearer ${accessToken}`,
  },
});

Server-Side Token Access

Access the OAuth provider's tokens for a user (useful for calling provider APIs on their behalf):

Get Provider Tokens

curl https://api.zyphr.dev/v1/auth/oauth/tokens/google \
  -H "X-Application-Key: za_pub_xxxx" \
  -H "X-Application-Secret: za_sec_xxxx" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/auth/oauth/tokens/google', {
  headers: {
    'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
    'X-Application-Secret': process.env.ZYPHR_APP_SECRET_KEY,
    'Authorization': `Bearer ${accessToken}`,
  },
});
// data.access_token — the provider's access token
// data.refresh_token — the provider's refresh token (if available)
// data.expires_at — token expiration

Refresh Provider Tokens

curl -X POST https://api.zyphr.dev/v1/auth/oauth/tokens/google/refresh \
  -H "X-Application-Key: za_pub_xxxx" \
  -H "X-Application-Secret: za_sec_xxxx" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Node.js

const response = await fetch('https://api.zyphr.dev/v1/auth/oauth/tokens/google/refresh', {
  method: 'POST',
  headers: {
    'X-Application-Key': process.env.ZYPHR_APP_PUBLIC_KEY,
    'X-Application-Secret': process.env.ZYPHR_APP_SECRET_KEY,
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
});

caution

Token access and refresh require both the application secret key and the user's access token. These endpoints are strictly server-side only.

Endpoint Reference

Method	Endpoint	Auth	Description
GET	/v1/auth/oauth/providers	Public key	List configured providers
GET	/v1/auth/oauth/:provider/authorize	Public key	Get authorization URL
POST	/v1/auth/oauth/:provider/callback	App credentials	Handle OAuth callback
GET	/v1/auth/oauth/connections	Public key + user token	List user's connections
GET	/v1/auth/oauth/connections/:provider	Public key + user token	Get connection details
DELETE	/v1/auth/oauth/:provider	Public key + user token	Disconnect provider
GET	/v1/auth/oauth/tokens/:provider	App credentials + user token	Get provider tokens
POST	/v1/auth/oauth/tokens/:provider/refresh	App credentials + user token	Refresh provider tokens