Quickstart

Add Whisp3r Auth sign-in to an existing app in about ten minutes. Any OIDC-compliant client library works — examples below use raw fetch so the protocol stays visible.

1. Register your app

Sign in to /dashboard/oauth-apps and click Register an app. You'll be asked for:

• Name — what your users will see on the consent screen.
• Redirect URIs — every URL your app calls back to after sign-in. HTTPS in production; HTTP localhost is OK for dev.
• Webhook URL — where to receive profile-change events. Required for every app.
• Scopes — what your app needs. Mark each as Required (must consent to sign in), Optional (user can opt in), or Skip.

On submit you'll get a client_id and (for confidential clients) a one-time client_secret. Store both — the secret is hashed server-side and cannot be retrieved later.

2. Discover the endpoints

Don't hard-code URLs. Every modern OIDC client (and every relying-party library) can read the discovery document at:

GET https://auth.whisp3r.com/.well-known/openid-configuration

You'll get back a JSON document listing every endpoint your client needs — authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, supported scopes, signing algorithms, etc. The full reference is at OIDC endpoints.

3. Send the user to authorize

Build an authorization URL with your client ID, the scopes you want, a redirect URI you registered above, a random state value (CSRF token), and a PKCE code challenge:

https://auth.whisp3r.com/oauth2/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth%2Fcallback
  &scope=openid%20wa%3Aname.first%20wa%3Aphoto
  &state=RANDOM_TOKEN
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

The user signs in (or consents if already signed in), then we redirect them back to your redirect_uri with ?code=…&state=….

4. Exchange the code for tokens

Verify the state matches what you sent, then POST the code to the token endpoint:

POST https://auth.whisp3r.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)   # confidential only

grant_type=authorization_code
&code=THE_CODE
&redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth%2Fcallback
&code_verifier=PKCE_VERIFIER

You get back:

{
  "access_token": "eyJhbGciOi...",
  "id_token":     "eyJhbGciOi...",
  "refresh_token":"...",
  "token_type":   "Bearer",
  "expires_in":   900
}

Verify the id_token signature against our JWKS (the jwks_uri from discovery). If you don't, you don't actually know who signed in. Most OIDC libraries verify automatically — if you're hand- rolling, see Token claims.

5. Use the access token

Fetch the user's profile (only fields the user consented to):

GET https://auth.whisp3r.com/oauth2/userinfo
Authorization: Bearer ACCESS_TOKEN

→ {
  "sub":        "pairwise-id-for-your-app",
  "name":       "Alex Rivera",
  "given_name": "Alex",
  "picture":    "https://media.whisp3r.com/avatars/<id>.jpg?v=1700000000000"
}

The sub is per-app — it's a deterministic hash of the user ID, your client ID, and our signing secret. The same user signing in to a different app gets a different sub. Use sub as the primary key in your users table.

picture is the user's photo URL directly — an absolute URL with a ?v=<timestamp> cache buster that changes on every upload, or null when they have no photo. Render your own initials / default mark on null; the platform does NOT ship a deterministic default-avatar URL.

6. Refresh when the access token expires

Access tokens last 15 minutes. When they expire, exchange the refresh token for a new pair:

POST https://auth.whisp3r.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

What's next

• Scopes reference — the full list of identity claims you can request.
• Email relay — send your users email without ever learning their address.
• Webhooks — get notified when a user updates their profile.