# Wicket > Wicket signs people in to an app with a link mailed to their address. It is an > OpenID Connect issuer that does one flow: Authorization Code with PKCE (S256), > for public clients. No client secrets, no refresh tokens. The ID token's `sub` > is the person's email address. This file is the integration guide for coding > agents; the same guide for people is https://wicketauth.com/guide/. ## 1. Register the app (one human step) Install the `wicket` CLI: one static file from https://wicketauth.com/cli/ curl -fsSLo wicket https://wicketauth.com/cli/wicket-x86_64-unknown-linux-musl # Linux x86_64 # wicket-aarch64-unknown-linux-musl, wicket-aarch64-apple-darwin, wicket-x86_64-apple-darwin chmod +x wicket Run: ./wicket setup --name "" \ --redirect-uri http://127.0.0.1:/callback It prints a link (https://login.wicketauth.com/cli?code=...) and a code. Show the person both: they open the link, sign in with their email the first time (their browser then stays signed in for 30 days), check the page shows the same code, and click Approve. That is the only human step; the command waits for it (up to 10 minutes) and then prints: client_id live_... issuer https://login.wicketauth.com discovery https://login.wicketauth.com/.well-known/openid-configuration # .env WICKET_ISSUER=https://login.wicketauth.com WICKET_CLIENT_ID=live_... Put the two `.env` lines in the app's config. Live accepts `http://127.0.0.1` redirect URIs, so this one app works in development and in production. To add the production callback later (the list given replaces the old one, so repeat the ones to keep): ./wicket apps update --redirect-uri http://127.0.0.1:/callback \ --redirect-uri https:///callback Want staging? Run `./wicket setup` again with the staging callback: a second app on the same issuer, with its own client_id. Add `--json` to any command for JSON on stdout. Without the CLI, the same calls with curl are in https://wicketauth.com/guide/#quick-start. ## 2. The values issuer https://login.wicketauth.com discovery /.well-known/openid-configuration authorization_endpoint /authorize token_endpoint /token jwks_uri https://login.wicketauth.com/jwks.json client authentication none (public client; there is no client secret) response_type code PKCE required, S256 only scope openid email ID token RS256, header typ "wicket-id+jwt", valid 10 minutes Most OIDC libraries, configured with the issuer (they read discovery), the client_id, no secret, PKCE on and scope `openid email`, need nothing else. That holds for a browser-only app (an SPA with no server) too: discovery, the JWKS and /token answer requests from any origin, so the whole flow, the code exchange included, can run in the browser. Three need more: Auth.js (NextAuth v5) needs two settings, below; Spring Security (Java) and Rust's `openidconnect` check the ID token's `typ`, `wicket-id+jwt`, and reject every Wicket ID token until told to accept it (their settings are in section 4). Most other libraries don't check `typ` at all, so check it yourself (section 4). Auth.js (NextAuth v5): Wicket has no userinfo endpoint, and Auth.js refuses a discovered server without one unless `token` is set; and it sends the client_id in a Basic header unless the client says `none`, where Wicket reads it only from the body. Without both, every sign-in spends the mailed link and ends on Auth.js's `error=Configuration` page. Register the redirect URI `https:///api/auth/callback/wicket`. // auth.ts import NextAuth from "next-auth"; export const { handlers, auth, signIn, signOut } = NextAuth({ providers: [ { id: "wicket", name: "Wicket", type: "oidc", issuer: "https://login.wicketauth.com", clientId: process.env.WICKET_CLIENT_ID, token: "https://login.wicketauth.com/token", // required: no userinfo client: { token_endpoint_auth_method: "none" }, // required: public client checks: ["pkce", "state"], }, ], }); Auth.js reads the ID token straight from /token and checks its claims itself; `session.user.email` is the person's address. ## 3. The flow 1. Make a random PKCE verifier (43-128 chars of `A-Z a-z 0-9 - . _ ~`), a random `state` and a random `nonce`; keep all three in the person's session. The challenge is base64url(sha256(verifier)), no padding. 2. Redirect the browser to: /authorize?client_id=&redirect_uri= &response_type=code&scope=openid%20email&code_challenge= &code_challenge_method=S256&state=&nonce= 3. The person types their address and opens the mailed link (it works once, for 15 minutes). Wicket redirects to `?code=...&state=...`. Check `state`. The code works once, for 5 minutes. The link works only in the browser that started the sign-in. Opened on another device, or in a mail app's own browser, it reaches the callback where no pending sign-in matches its `state`. Most libraries throw there; catch it and show a page instead: "Open the link on the device and in the browser where you asked to sign in, or ask for a new link here.", with a button that starts a new sign-in. The link is used up by then, and the code can't be traded without the verifier, so a new sign-in is the only way on. 4. Exchange it (form-encoded; JSON with `Content-Type: application/json` works too): POST /token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=&client_id= &redirect_uri=&code_verifier= Answer: `{"access_token": "...", "id_token": "eyJ...", "token_type": "Bearer", "expires_in": 600}`. Errors are RFC 6749 5.2's, `{"error": , "error_description": "..."}`: 400 `invalid_request` (missing or malformed parameter), `invalid_grant` (code unknown, used or expired, or wrong verifier, redirect_uri or client_id for it) or `unsupported_grant_type`; 401 `invalid_client` (unknown client_id). An authorize request without an S256 code_challenge returns to the redirect_uri with `error=invalid_request&error_description=...&state=...`; one with `prompt=none` returns with `error=login_required`. 5. Verify the ID token (below), then start the app's own session for `sub`. ## 4. Verify the ID token Check all of: the RS256 signature with the JWKS key whose `kid` matches the header; header `typ` is `wicket-id+jwt`; `iss` equals the issuer exactly; `aud` is your client_id; `exp` hasn't passed; `nonce` is the one you sent. Claims: `sub` and `email` (the address, trimmed and lowercased), `email_verified` (always true), `iss`, `aud`, `iat`, `exp`, `nonce` (if sent). Python (PyJWT, `pip install "pyjwt[crypto]"`): import os import jwt ISSUER = os.environ["WICKET_ISSUER"] CLIENT_ID = os.environ["WICKET_CLIENT_ID"] jwks = jwt.PyJWKClient(ISSUER + "/jwks.json") def verify(id_token: str, nonce: str) -> str: if jwt.get_unverified_header(id_token).get("typ") != "wicket-id+jwt": raise ValueError("not a Wicket ID token") key = jwks.get_signing_key_from_jwt(id_token) claims = jwt.decode(id_token, key.key, algorithms=["RS256"], audience=CLIENT_ID, issuer=ISSUER) if claims.get("nonce") != nonce: raise ValueError("nonce mismatch") return claims["sub"] # "alice@example.com" TypeScript / Node (jose, `npm i jose`): import { createRemoteJWKSet, jwtVerify } from "jose"; const ISSUER = process.env.WICKET_ISSUER!; const CLIENT_ID = process.env.WICKET_CLIENT_ID!; const jwks = createRemoteJWKSet(new URL(ISSUER + "/jwks.json")); export async function verify(idToken: string, nonce: string): Promise { const { payload } = await jwtVerify(idToken, jwks, { issuer: ISSUER, audience: CLIENT_ID, algorithms: ["RS256"], typ: "wicket-id+jwt", }); if (payload.nonce !== nonce) throw new Error("nonce mismatch"); return payload.sub!; // "alice@example.com" } Go (go-oidc, `go get github.com/coreos/go-oidc/v3/oidc`; it checks the signature, iss, aud and exp, but not typ, so check that first): import ( "context" "encoding/base64" "encoding/json" "errors" "os" "strings" "github.com/coreos/go-oidc/v3/oidc" ) // Once, at startup: reads discovery and caches the JWKS. func NewVerifier(ctx context.Context) (*oidc.IDTokenVerifier, error) { provider, err := oidc.NewProvider(ctx, os.Getenv("WICKET_ISSUER")) if err != nil { return nil, err } return provider.Verifier(&oidc.Config{ClientID: os.Getenv("WICKET_CLIENT_ID")}), nil } func Verify(ctx context.Context, v *oidc.IDTokenVerifier, raw, nonce string) (string, error) { head, err := base64.RawURLEncoding.DecodeString(strings.SplitN(raw, ".", 2)[0]) if err != nil { return "", err } var h struct{ Typ string `json:"typ"` } if err := json.Unmarshal(head, &h); err != nil || h.Typ != "wicket-id+jwt" { return "", errors.New("not a Wicket ID token") } tok, err := v.Verify(ctx, raw) if err != nil { return "", err } if tok.Nonce != nonce { return "", errors.New("nonce mismatch") } return tok.Subject, nil // "alice@example.com" } Rust (jsonwebtoken, `jsonwebtoken = { version = "12", features = ["rust_crypto"] }`; fetch `/jwks.json` into a `JwkSet` with any HTTP client, e.g. `reqwest::get(url).await?.json::().await?`, and fetch it again when a `kid` isn't in it): use jsonwebtoken::{decode, decode_header, jwk::JwkSet, Algorithm, DecodingKey, Validation}; use serde::Deserialize; #[derive(Deserialize)] struct Claims { sub: String, nonce: Option, } fn verify(id_token: &str, jwks: &JwkSet, issuer: &str, client_id: &str, nonce: &str) -> Result> { let header = decode_header(id_token)?; if header.typ.as_deref() != Some("wicket-id+jwt") { return Err("not a Wicket ID token".into()); } let jwk = jwks.find(header.kid.as_deref().ok_or("no kid")?).ok_or("unknown kid")?; let mut v = Validation::new(Algorithm::RS256); v.set_issuer(&[issuer]); v.set_audience(&[client_id]); let claims = decode::(id_token, &DecodingKey::from_jwk(jwk)?, &v)?.claims; if claims.nonce.as_deref() != Some(nonce) { return Err("nonce mismatch".into()); } Ok(claims.sub) // "alice@example.com" } Java (Spring Security `oauth2Login()`, 6.4 to 7.1). Spring checks `typ` itself and accepts only `JWT`, so without this bean every sign-in fails after the code exchange with `[invalid_id_token] ... typ ... not allowed` (6.x) or `the given typ value needs to be one of [JWT]` (7.x). The bean replaces Spring's ID token decoder with one that accepts `wicket-id+jwt` and nothing else, and keeps Spring's other checks (iss, aud, exp, signature; Spring checks nonce itself): import com.nimbusds.jose.JOSEObjectType; import com.nimbusds.jose.proc.DefaultJOSEObjectTypeVerifier; import org.springframework.context.annotation.Bean; import org.springframework.security.oauth2.client.oidc.authentication.OidcIdTokenDecoderFactory; import org.springframework.security.oauth2.client.oidc.authentication.OidcIdTokenValidator; import org.springframework.security.oauth2.client.registration.ClientRegistration; import org.springframework.security.oauth2.core.DelegatingOAuth2TokenValidator; import org.springframework.security.oauth2.jwt.JwtDecoder; import org.springframework.security.oauth2.jwt.JwtDecoderFactory; import org.springframework.security.oauth2.jwt.JwtTimestampValidator; import org.springframework.security.oauth2.jwt.NimbusJwtDecoder; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; @Bean JwtDecoderFactory wicketIdTokenDecoderFactory() { Map decoders = new ConcurrentHashMap<>(); // one per app, so the JWKS stays cached return registration -> decoders.computeIfAbsent(registration.getRegistrationId(), id -> { NimbusJwtDecoder decoder = NimbusJwtDecoder .withJwkSetUri(registration.getProviderDetails().getJwkSetUri()) .jwtProcessorCustomizer(p -> p.setJWSTypeVerifier( new DefaultJOSEObjectTypeVerifier<>(new JOSEObjectType("wicket-id+jwt")))) .build(); decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>( new JwtTimestampValidator(), new OidcIdTokenValidator(registration))); decoder.setClaimSetConverter(OidcIdTokenDecoderFactory.createDefaultClaimTypeConverter()); return decoder; }); } With Spring Boot, the registration is (a public client, so Spring sends PKCE): spring.security.oauth2.client.provider.wicket.issuer-uri=https://login.wicketauth.com spring.security.oauth2.client.registration.wicket.client-id=${WICKET_CLIENT_ID} spring.security.oauth2.client.registration.wicket.client-authentication-method=none spring.security.oauth2.client.registration.wicket.authorization-grant-type=authorization_code spring.security.oauth2.client.registration.wicket.scope=openid,email Rust (openidconnect 4). Its ID token verifier accepts only `typ` `JWT` or `JOSE` by default and rejects Wicket's with ``unexpected or unsupported JWT type `wicket-id+jwt` ``; allow Wicket's instead: use openidconnect::JsonWebTokenType; let verifier = client.id_token_verifier().set_allowed_jose_types([ JsonWebTokenType::new("wicket-id+jwt".to_string()).normalize()?, ]); let claims = id_token.claims(&verifier, &nonce)?; ## 5. Mistakes to avoid - redirect_uri must match a registered one exactly, character for character (scheme, host, port, path, trailing slash), and be the same string in /authorize and /token. `localhost` is not `127.0.0.1`. - iss is `https://login.wicketauth.com` byte for byte: no trailing slash. Pin it; don't build it from a request. - Check the header's `typ` is `wicket-id+jwt`. Most libraries don't check `typ` at all; Spring Security and Rust's `openidconnect` reject anything but `JWT` until configured as in section 4. - Check `aud` is your client_id, and `nonce` is the one you stored for this sign-in. - No refresh tokens, and no `offline_access`. The ID token lasts 10 minutes: start your own session from it; when that ends, sign the person in again. - The `access_token` is required by OAuth but grants nothing; don't call anything with it, and don't use it as the user's identity. - No silent sign-in: Wicket keeps no session, so `prompt=none` always returns `error=login_required`. Turn silent renew off (oidc-client-ts: `automaticSilentRenew: false`). - No client secret: configure a public client (`token_endpoint_auth_method` `none`), with PKCE S256. - The mailed link works only in the browser that started the sign-in, wherever the PKCE verifier and state live (a cookie, a server session behind one, localStorage or sessionStorage): another device or another browser, such as the one inside a phone's mail app, can't see them. sessionStorage is per tab, and a mailed link opens in a new tab, so keep them in a cookie or localStorage. Handle the callback that finds none as in section 3, step 3. - Cache the JWKS, and fetch it again when a token names a `kid` you don't have: keys rotate. ## 6. Managing apps from code The CLI's credential (`wkt_live_...`, a person's own key for managing their apps; it signs nobody in) is the only bearer the apps API takes: GET /api/apps your apps POST /api/apps {"name", "redirect_uris": [...]} 201, the app GET /api/apps/{client_id} PUT /api/apps/{client_id} {"name", "redirect_uris": [...]} replaces both DELETE /api/apps/{client_id} 204 POST /api/apps/{client_id}/checkout {"plan": "starter" or "pro"} {"url"}: Stripe Checkout for it DELETE /api/credential revokes the presenting credential Every call sends `Authorization: Bearer wkt_...`. The CLI keeps it 0600 in the user's config dir; it expires after 90 days unused. Registering an app (`POST /api/apps`, `wicket setup`, or the dashboard) means the person accepts Wicket's terms: https://wicketauth.com/terms/ ## More - Guide for people: https://wicketauth.com/guide/ - CLI downloads and commands: https://wicketauth.com/cli/ - What Wicket will never do (pairwise subjects, refresh tokens, client secrets, changing an address): https://wicketauth.com/#never - Plans, per app: Personal (free; only the developer's own address and its plus-addresses can sign in, anyone else is refused before any email is sent), Starter ($5 a month, up to 100 monthly active users), Pro ($20 a month, up to 1,000). Past a plan's limit, Pro's 1,000 included, new people are refused. A new app is on Personal: it is enough for the developer to try sign-in, and the person upgrades it in the dashboard before other people sign in. Starter and Pro are available to customers in the United States for now. `wicket upgrade --plan starter` (or `pro`) prints the Checkout link; paying is the person's, and they switch between Starter and Pro in the dashboard's Manage billing.