Paswad Developer Docs

Introduction

Paswad lets people log into your application with a passkey instead of a password. “Sign in with Paswad” is, under the hood, a textbook OAuth 2.1 Authorization Code flow with PKCE, layered with OpenID Connect for identity. If you have integrated “Sign in with Google” before, this will feel familiar.

Environments & base URLs

Paswad runs on a small set of stable hosts. Point your OIDC client at the discovery document and it will pick up the rest automatically.

Key URLs

Quickstart

Register your application once, then wire up the redirect flow.

1. Create an app in the Console. Go to console.paswad.com and create a new application. You will receive a client_id (public) and a client_secret (confidential — store it server-side only).
2. Register your redirect URIs. Add every exact callback URL your app uses, e.g. https://yourapp.com/auth/callback. Redirect URIs are matched exactly — protocol, host, port, and path all have to match a registered entry.
3. Pick your scopes. Start with openid profile email. See the scopes table below.
4. Send users through the flow. Redirect to the authorization endpoint, exchange the returned code for tokens, then read the user info.

Authorization Code + PKCE

Generate a PKCE code_verifier (a high-entropy random string) and its code_challenge (the base64url-encoded SHA-256 of the verifier). Keep the verifier; send the challenge. Also generate a random state (CSRF protection) and nonce (replay protection for the ID token), and store them in the user’s session.

GET https://id.paswad.com/authorize
  ?response_type=code
  &client_id=app_live_a1b2c3
  &redirect_uri=https://yourapp.com/auth/callback
  &scope=openid%20profile%20email
  &state=xyz_random_state
  &nonce=n_random_nonce
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

The user signs in with their passkey and approves the requested scopes. Paswad then redirects the browser back to your redirect_uri with a short-lived authorization code and the state you sent:

https://yourapp.com/auth/callback
  ?code=ac_8f3d0b1e2c
  &state=xyz_random_state

Token exchange

Exchange the authorization code for tokens by POSTing to the token endpoint from your server. Include the original code_verifier — Paswad re-derives the challenge and checks it against the one from step 1.

curl -X POST https://api.paswad.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=ac_8f3d0b1e2c \
  -d redirect_uri=https://yourapp.com/auth/callback \
  -d client_id=app_live_a1b2c3 \
  -d client_secret=sk_live_REPLACE_ME \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

{
  "access_token": "at_live_b7c1...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "rt_live_9a2f...",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "scope": "openid profile email"
}

Node.js example

const res = await fetch("https://api.paswad.com/v1/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code,                        // from the callback query
    redirect_uri: "https://yourapp.com/auth/callback",
    client_id: process.env.PASWAD_CLIENT_ID,
    client_secret: process.env.PASWAD_CLIENT_SECRET,
    code_verifier: codeVerifier, // the one you stored in step 1
  }),
});

const tokens = await res.json();
// tokens.access_token, tokens.id_token, tokens.refresh_token

User info

With a valid access token you can fetch the authenticated user’s profile from the OIDC UserInfo endpoint. The claims returned depend on the scopes you were granted.

curl https://api.paswad.com/v1/oauth/userinfo \
  -H "Authorization: Bearer at_live_b7c1..."

{
  "sub": "usr_2Hk9c1qZ",
  "name": "Ada Lovelace",
  "email": "[email protected]",
  "email_verified": true
}

Scopes

Request the least you need. These standard scopes are available to every app by default:

Verifying tokens (JWKS)

ID tokens are signed JWTs. Verify them against Paswad’s public signing keys, published as a JWKS. Most OIDC libraries fetch and cache this for you automatically when you point them at the discovery document.

GET https://api.paswad.com/.well-known/openid-configuration

GET https://api.paswad.com/.well-known/jwks.json

When validating an id_token, check that:

• the signature verifies against the JWKS key matching the token’s kid;
• iss equals https://id.paswad.com;
• aud equals your client_id;
• exp is in the future and nonce matches what you sent.

import * as jose from "jose";

const JWKS = jose.createRemoteJWKSet(
  new URL("https://api.paswad.com/.well-known/jwks.json")
);

const { payload } = await jose.jwtVerify(idToken, JWKS, {
  issuer: "https://id.paswad.com",
  audience: process.env.PASWAD_CLIENT_ID,
});
// payload.sub, payload.email, payload.nonce ...

Errors

Failed requests return a JSON envelope with a stable, machine-readable error code and a human-readable error_description. OAuth endpoints follow the standard OAuth 2.0 / OIDC error shape.

{
  "error": "invalid_grant",
  "error_description": "The authorization code is expired or already used.",
  "request_id": "req_5fK0pQ"
}

Log the request_id — it helps when you contact support. Common HTTP statuses:

Rate limits

All endpoints are rate-limited to keep the platform fast and fair. Limits are applied per application and may differ by endpoint. When you exceed a limit you receive a 429 Too Many Requests with a Retry-After header telling you how many seconds to wait before retrying.

Every response also carries informational headers so you can pace yourself before hitting the limit:

Sessions & logout

Tokens are intentionally short-lived. An access_token expires quickly (illustratively in minutes), and your app keeps the user signed in by quietly exchanging the refresh_token for a fresh one when needed. This keeps a leaked access token useful only briefly.

Signing a user out

• Local sign-out. Clear the user’s session in your own app and discard the tokens you stored. This logs them out of your app.
• Token revocation. To invalidate a refresh_token (or access token) immediately — for example on “log out everywhere” — revoke it so it can no longer be exchanged. The discovery document advertises the revocation endpoint.
• RP-initiated logout. To also end the user’s Paswad session, send them to the OIDC end-session (RP-initiated logout) endpoint advertised in discovery, with your post_logout_redirect_uri registered in the Console.

Webhooks

Subscribe to events to keep your app in sync with identity changes. Add a webhook endpoint in the Console and select the events you care about. Every delivery is an HTTP POST with a JSON body and is HMAC-signed so you can verify it came from Paswad.

{
  "id": "evt_4tP0aZ",
  "type": "user.signed_in",
  "created": 1773600000,
  "data": {
    "sub": "usr_2Hk9c1qZ",
    "client_id": "app_live_a1b2c3"
  }
}

Security best practices

Paswad is secure by default, but the integration is a shared responsibility. Run through this checklist before you ship:

• Always use PKCE with S256. Never plain. Generate a fresh code_verifier per authorization request.
• Validate state and nonce. Reject the callback if state does not match what you stored; reject the ID token if nonce does not.
• Verify the ID token signature. Check the JWKS signature plus iss, aud, and exp — see Verifying tokens.
• Keep client_secret server-side only. Never ship it in browser, mobile, or SPA code. Do the token exchange on your backend.
• Register exact redirect URIs. No wildcards. Match protocol, host, port, and path.
• Use HTTPS everywhere. For your redirect URIs, webhook endpoints, and all API calls.
• Rotate secrets. Rotate client_secret and webhook signing secrets periodically and immediately if you suspect exposure.
• Verify webhook signatures. Constant-time compare the Paswad-Signature header before acting on a delivery.

SDKs & libraries

Because Paswad is a standards-compliant OAuth 2.1 + OpenID Connect provider, you do not need a Paswad-specific SDK. Any certified OIDC client library works — just point it at the discovery document. Some widely used options:

Integration guides

Because Paswad is a standards-compliant OAuth 2.1 / OpenID Connect provider, it works as an external identity (SSO) provider for any app that speaks OIDC or generic OAuth 2. The pattern is always the same: create an OAuth app in the Paswad Console, register the exact callback URL the platform expects, copy the client_id / client_secret, and point the platform at Paswad’s endpoints. Use these hosts everywhere:

Plugins

Paswad ships official and community plugins so you can add “Sign in with Paswad” to popular platforms without writing any OAuth code by hand. Every plugin is a thin wrapper around the same OAuth 2.1 / OpenID Connect endpoints documented above — they handle the redirect, the PKCE code exchange, and the id_token validation for you, so you just paste a client_id / client_secret from the Paswad Console and go.

Paswad for WordPress

Other plugins

Native plugins for more platforms are on the way. Until one ships, you can connect any of these today via the generic OIDC integration guides above — Paswad is a standard OpenID Connect provider, so any platform that speaks OIDC or OAuth 2 can sign in with Paswad now.

• ShopifyComing soon

  Storefront & customer accounts. For now, integrate via the generic OIDC guide.

• DrupalComing soon

  CMS & sites. Until the native module ships, use the generic OIDC guide.

• JoomlaComing soon

  CMS & publishing. Connect today via the generic OIDC guide.

• MagentoComing soon

  Adobe Commerce storefronts. Use the generic OIDC guide in the meantime.

• GhostComing soon

  Publishing & memberships. Integrate now via the generic OIDC guide.

Endpoint reference

The complete public integration surface: