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

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 (optional) — where to receive profile-change events.
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=….

PKCE is required. Confidential clients (with a secret) AND public clients must include code_challenge. Auth code grant without PKCE is rejected.

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://auth.whisp3r.com/api/avatar/..."
}

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.

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.