OIDC API
Exchange token
POST /api/v1/oidc/kupeana and /shake — trade handshake for Bearer access.
POST /api/v1/oidc/kupeana
Alias: POST /api/v1/oidc/shake (identical)
Header: Authorization: Shake <handshake-jwt>
| Field | Type | Required |
|---|---|---|
verifier | string | Yes — PKCE code verifier |
Success (typical): 200
| Field | Use |
|---|---|
data.access | Bearer token for resource |
data.challenge | Required on next resource call |
data.type | Bearer |
data.exp | Expiry — drive your session TTL |
Access tokens are short-lived (~25 minutes in current behavior). Store securely; do not log full tokens.
The session challenge is not PKCE — see PKCE.
SDK usage
// Handled by GET /api/eid/handshake inside handler().
// Reads handshake query params + PKCE cookie, sets session cookies.Full guide: Next.js OIDC
import { tokenSwap } from "@finsel-dgi/pasby-react/server";
const { access, challenge, exp } = await tokenSwap({
flow: req.query.flow as string, // session id from callback
code: req.query.handshake as string, // Shake JWT from callback
pkceverifier: req.cookies.pasby_pkce, // from loginWithSecret
});
// access + challenge are encrypted for cookie storage
// pass to eidResource or set httpOnly cookiesFull guide: React OIDC
// POST https://oauth.pasby.africa/api/v1/oidc/kupeana
// Header: Authorization: Shake <handshake-jwt>
// Body: {"verifier":"<pkce-verifier-from-step-1>"}Related
- Start session
- Get user claims
- Errors — expired handshake, PKCE mismatch