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

Provider Setup

Before using OAuth, you need to create credentials in the provider's developer console and configure them in the Zyphr dashboard under Applications → [Your App] → OAuth.

Google

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Web application
4. Add your authorized redirect URI: https://yourapp.com/auth/callback
5. Copy the Client ID and Client Secret

Zyphr Dashboard Field	Value
Provider	Google
Client ID	xxxx.apps.googleusercontent.com
Client Secret	GOCSPX-xxxx
Scopes	openid, email, profile (pre-populated)

Apple

1. Go to Apple Developer → Certificates, Identifiers & Profiles
2. Create an App ID with "Sign in with Apple" enabled
3. Create a Services ID (this is your Client ID) — enable "Sign in with Apple" and configure your domain + redirect URI
4. Create a Key with "Sign in with Apple" enabled — download the .p8 file (you can only download it once)
5. Note your Team ID (top-right of the developer portal) and Key ID (shown on the key page)

Zyphr Dashboard Field	Value
Provider	Apple
Client ID	Your Services ID (e.g., com.yourapp.auth)
Private Key (PEM)	Paste the full contents of the .p8 file including -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----
Team ID	Your 10-character Apple Team ID (e.g., BQM826CZF5)
Key ID	Your 10-character Key ID (e.g., 5C74AD92FS)
Scopes	name, email (pre-populated)

Apple name is only sent once

Apple only sends the user's name on the first authorization. Make sure your callback handler forwards the user JSON from Apple's form_post body to Zyphr's callback endpoint:

{
  "code": "...",
  "state": "...",
  "user": { "name": { "firstName": "Jane", "lastName": "Doe" } }
}

On subsequent logins, user won't be present and the name will be retrieved from the stored profile.

GitHub

1. Go to GitHub Developer Settings → OAuth Apps → New OAuth App
2. Set the Authorization callback URL to your redirect URI
3. Copy the Client ID and generate a Client Secret

Zyphr Dashboard Field	Value
Provider	GitHub
Client ID	Iv1.xxxx
Client Secret	xxxx
Scopes	read:user, user:email (pre-populated)

Facebook

1. Go to Meta for Developers → My Apps → Create App
2. Add Facebook Login product and configure your redirect URI under Valid OAuth Redirect URIs
3. Copy the App ID and App Secret from Settings → Basic

Zyphr Dashboard Field	Value
Provider	Facebook
Client ID	Your App ID
Client Secret	Your App Secret
Scopes	email, public_profile (pre-populated)

Microsoft

1. Go to Azure Portal → Azure Active Directory → App registrations → New registration
2. Set the redirect URI (Web platform) to your callback URL
3. Create a Client secret under Certificates & secrets
4. Copy the Application (client) ID from the Overview page

Zyphr Dashboard Field	Value
Provider	Microsoft
Client ID	Your Application (client) ID
Client Secret	Your client secret value
Scopes	openid, email, profile, User.Read (pre-populated)

---

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:

Node.js SDK

const zyphr = new Zyphr({
  apiKey: process.env.ZYPHR_API_KEY!,
  applicationKey: process.env.ZYPHR_APP_PUBLIC_KEY!,
  applicationSecret: process.env.ZYPHR_APP_SECRET_KEY!,
});

// Note: positional arguments, NOT an object
const result = await zyphr.auth.oauth.getOAuthAuthorizationUrl(
  'google',                              // provider (positional)
  'https://myapp.com/auth/callback',     // redirectUri (positional)
);
// result.data.authorization_url — redirect the user here
// result.data.state — CSRF state parameter (validated on callback)

cURL

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

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:

Node.js SDK

// Note: positional arguments, NOT an object
const result = await zyphr.auth.oauth.handleOAuthCallback(
  'google',                              // provider (positional)
  {                                      // oAuthCallbackRequest (positional)
    code: oauthCode,
    state: oauthState,
    redirect_uri: 'https://myapp.com/auth/callback',
  },
);
// result.data.user — the authenticated user
// result.data.tokens — { access_token, refresh_token, expires_in }
// result.data.is_new_user — true if this was their first login

cURL

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"
  }'

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