Paswad Entwicklerdokumentation

Einführung

Paswad ermöglicht es Menschen, sich mit einem Passkey statt einem Passwort in Ihre Anwendung einzuloggen. “Sign in with Paswad” ist im Kern ein lehrbuchmäßiger OAuth 2.1-Authorization-Code-Flow mit PKCE, ergänzt um OpenID Connect für Identität. Wenn Sie zuvor „Sign in with Google“ integriert haben, wird Ihnen dies vertraut vorkommen.

Umgebungen & Basis-URLs

Paswad läuft auf einer kleinen Anzahl stabiler Hosts. Richten Sie Ihren OIDC-Client auf das Discovery-Dokument aus, und er ermittelt den Rest automatisch.

Wichtige URLs

Schnellstart

Registrieren Sie Ihre Anwendung einmal und richten Sie dann den Redirect-Flow ein.

1. Erstellen Sie eine App in der Console. Gehen Sie zu console.paswad.com und erstellen Sie eine neue Anwendung. Sie erhalten eine client_id (öffentlich) und ein client_secret (vertraulich — bewahren Sie es ausschließlich serverseitig auf).
2. Registrieren Sie Ihre Redirect-URIs. Fügen Sie jede exakte Callback-URL hinzu, die Ihre App verwendet, z. B. https://yourapp.com/auth/callback. Redirect-URIs werden exakt abgeglichen — Protokoll, Host, Port und Pfad müssen alle mit einem registrierten Eintrag übereinstimmen.
3. Wählen Sie Ihre Scopes. Beginnen Sie mit openid profile email. Siehe die Scopes-Tabelle unten.
4. Führen Sie Nutzer durch den Flow. Leiten Sie zum Authorization-Endpunkt weiter, tauschen Sie den zurückgegebenen Code gegen Tokens und lesen Sie dann die Benutzerinformationen.

Authorization Code + PKCE

Erzeugen Sie einen PKCE-code_verifier (eine zufällige Zeichenfolge mit hoher Entropie) und dessen code_challenge (das base64url-kodierte SHA-256 des Verifiers). Behalten Sie den Verifier; senden Sie die Challenge. Erzeugen Sie außerdem ein zufälliges state (CSRF-Schutz) und nonce (Replay-Schutz für das ID-Token) und speichern Sie sie in der Sitzung des Nutzers.

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

Der Nutzer meldet sich mit seinem Passkey an und genehmigt die angeforderten Scopes. Paswad leitet den Browser anschließend zurück an Ihre redirect_uri mit einem kurzlebigen Authorization-code und dem state, das Sie gesendet haben:

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

Token-Austausch

Tauschen Sie den Authorization-code gegen Tokens aus, indem Sie von Ihrem Server aus per POST an den Token-Endpunkt senden. Fügen Sie den ursprünglichen code_verifier hinzu — Paswad leitet die Challenge erneut ab und prüft sie gegen die aus Schritt 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-Beispiel

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

Benutzerinformationen

Mit einem gültigen Access-Token können Sie das Profil des authentifizierten Nutzers vom OIDC-UserInfo-Endpunkt abrufen. Die zurückgegebenen Claims hängen von den Scopes ab, die Ihnen gewährt wurden.

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

Fordern Sie nur das Nötigste an. Diese Standard-Scopes sind standardmäßig für jede App verfügbar:

Tokens verifizieren (JWKS)

ID-Tokens sind signierte JWTs. Verifizieren Sie sie gegen Paswads öffentliche Signierschlüssel, die als JWKS veröffentlicht werden. Die meisten OIDC-Bibliotheken rufen und cachen dies automatisch für Sie, wenn Sie sie auf das Discovery-Dokument ausrichten.

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

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

Prüfen Sie beim Validieren eines id_token, dass:

• die Signatur gegen den JWKS-Schlüssel verifiziert, der zum kid des Tokens passt;
• iss gleich https://id.paswad.com ist;
• aud gleich Ihrer client_id ist;
• exp in der Zukunft liegt und nonce mit dem von Ihnen gesendeten übereinstimmt.

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 ...

Fehler

Fehlgeschlagene Anfragen geben einen JSON-Umschlag mit einem stabilen, maschinenlesbaren error-Code und einer menschenlesbaren error_description zurück. OAuth-Endpunkte folgen der standardmäßigen OAuth-2.0-/OIDC-Fehlerform.

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

Protokollieren Sie die request_id — sie hilft, wenn Sie den Support kontaktieren. Häufige HTTP-Status:

Rate-Limits

Alle Endpunkte sind rate-limitiert, um die Plattform schnell und fair zu halten. Limits werden pro Anwendung angewendet und können je nach Endpunkt variieren. Wenn Sie ein Limit überschreiten, erhalten Sie ein 429 Too Many Requests mit einem Retry-After-Header, der angibt, wie viele Sekunden Sie vor einem erneuten Versuch warten sollen.

Jede Antwort enthält außerdem informative Header, sodass Sie sich vor dem Erreichen des Limits selbst takten können:

Sitzungen & Abmeldung

Tokens sind bewusst kurzlebig. Ein access_token läuft schnell ab (beispielhaft in Minuten), und Ihre App hält den Nutzer angemeldet, indem sie das refresh_token bei Bedarf still gegen ein frisches austauscht. So bleibt ein geleaktes Access-Token nur kurz nützlich.

Einen Nutzer abmelden

• Lokale Abmeldung. Löschen Sie die Sitzung des Nutzers in Ihrer eigenen App und verwerfen Sie die von Ihnen gespeicherten Tokens. Dies meldet ihn aus Ihrer App ab.
• Token-Widerruf. Um ein refresh_token (oder Access-Token) sofort zu invalidieren — etwa bei „überall abmelden“ — widerrufen Sie es, sodass es nicht mehr ausgetauscht werden kann. Das Discovery-Dokument gibt den Widerrufs-Endpunkt bekannt.
• RP-initiierte Abmeldung. Um auch die Paswad-Sitzung des Nutzers zu beenden, leiten Sie ihn an den OIDC-End-Session-Endpunkt (RP-initiierte Abmeldung) weiter, der in der Discovery angegeben ist, mit Ihrer in der Console registrierten post_logout_redirect_uri.

Webhooks

Abonnieren Sie Events, um Ihre App mit Identitätsänderungen synchron zu halten. Fügen Sie in der Console einen Webhook-Endpunkt hinzu und wählen Sie die Events aus, die Sie interessieren. Jede Zustellung ist ein HTTP-POST mit einem JSON-Body und ist HMAC-signiert, sodass Sie verifizieren können, dass sie von Paswad stammt.

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

Best Practices für Sicherheit

Paswad ist standardmäßig sicher, doch die Integration ist eine geteilte Verantwortung. Gehen Sie diese Checkliste durch, bevor Sie ausliefern:

• Verwenden Sie immer PKCE mit S256. Niemals plain. Erzeugen Sie einen frischen code_verifier pro Authorization-Anfrage.
• Validieren Sie state und nonce. Weisen Sie den Callback zurück, wenn state nicht mit dem von Ihnen gespeicherten übereinstimmt; weisen Sie das ID-Token zurück, wenn nonce es nicht tut.
• Verifizieren Sie die ID-Token-Signatur. Prüfen Sie die JWKS-Signatur sowie iss, aud und exp — siehe Tokens verifizieren.
• Halten Sie das client_secret ausschließlich serverseitig. Liefern Sie es niemals in Browser-, Mobil- oder SPA-Code aus. Führen Sie den Token-Austausch in Ihrem Backend durch.
• Registrieren Sie exakte Redirect-URIs. Keine Wildcards. Stimmen Sie Protokoll, Host, Port und Pfad ab.
• Verwenden Sie überall HTTPS. Für Ihre Redirect-URIs, Webhook-Endpunkte und alle API-Aufrufe.
• Rotieren Sie Secrets. Rotieren Sie client_secret und Webhook-Signiergeheimnisse regelmäßig und sofort, wenn Sie eine Offenlegung vermuten.
• Verifizieren Sie Webhook-Signaturen. Vergleichen Sie den Paswad-Signature-Header in konstanter Zeit, bevor Sie auf eine Zustellung reagieren.

SDKs & Bibliotheken

Da Paswad ein standardkonformer OAuth 2.1 + OpenID Connect-Provider ist, benötigen Sie kein Paswad-spezifisches SDK. Jede zertifizierte OIDC-Client-Bibliothek funktioniert — richten Sie sie einfach auf das Discovery-Dokument aus. Einige weit verbreitete Optionen:

Integrationsanleitungen

Da Paswad ein standardkonformer OAuth 2.1 / OpenID Connect-Provider ist, funktioniert es als externer Identitäts-(SSO-)Provider für jede App, die OIDC oder generisches OAuth 2 spricht. Das Muster ist immer dasselbe: Erstellen Sie eine OAuth-App in der Paswad Console, registrieren Sie die exakte Callback-URL, die die Plattform erwartet, kopieren Sie die client_id / das client_secret und richten Sie die Plattform auf Paswads Endpunkte aus. Verwenden Sie überall diese Hosts:

Plugins

Paswad liefert offizielle und Community-Plugins, sodass Sie “Sign in with Paswad” zu beliebten Plattformen hinzufügen können, ohne OAuth-Code von Hand zu schreiben. Jedes Plugin ist ein schlanker Wrapper um dieselben OAuth 2.1 / OpenID Connect- Endpunkte, die oben dokumentiert sind — sie handhaben den Redirect, den PKCE-Code-Austausch und die id_token-Validierung für Sie, sodass Sie nur eine client_id / ein client_secret aus der Paswad Console einfügen und loslegen.

Paswad für WordPress

Weitere Plugins

Native Plugins für weitere Plattformen sind in Arbeit. Bis eines erscheint, können Sie alle davon schon heute über die generischen OIDC-Integrationsanleitungen oben anbinden — Paswad ist ein standardkonformer OpenID Connect-Provider, sodass jede Plattform, die OIDC oder OAuth 2 spricht, sich jetzt mit Paswad anmelden kann.

• ShopifyDemnächst

  Storefront & Kundenkonten. Vorerst integrieren Sie über die generische OIDC-Anleitung.

• DrupalDemnächst

  CMS & Websites. Bis das native Modul erscheint, nutzen Sie die generische OIDC-Anleitung.

• JoomlaDemnächst

  CMS & Publishing. Binden Sie es schon heute über die generische OIDC-Anleitung an.

• MagentoDemnächst

  Adobe-Commerce-Storefronts. Nutzen Sie in der Zwischenzeit die generische OIDC-Anleitung.

• GhostDemnächst

  Publishing & Mitgliedschaften. Integrieren Sie jetzt über die generische OIDC-Anleitung.

Endpunkt-Referenz

Die vollständige öffentliche Integrationsoberfläche: