Wicket

Integration guide

Wicket is an OpenID Connect issuer that does one flow: Authorization Code with PKCE, for public clients. If you have used an OIDC provider before, the values below are all you need. Before you start, read what Wicket will never do.

Quick start: with a coding agent

Paste this into your coding agent:

Add Wicket sign-in to this app. Install the wicket CLI from
https://wicketauth.com/cli/ and run wicket setup with this app's name and
an http://127.0.0.1 callback URL. Show me the link it prints: I'll open it
and approve (the first time, I sign in with my email). Then follow
https://wicketauth.com/llms.txt to add sign-in, using the WICKET_ISSUER and
WICKET_CLIENT_ID it prints.

The agent does the rest. What it runs:

  1. Install the CLI, one static file from /cli/.
  2. wicket setup:
    wicket setup --name "My app" \
      --redirect-uri http://127.0.0.1:3000/callback
  3. You open the link it prints and click Approve. The first time, you sign in to the dashboard with your email first; your browser then stays signed in for 30 days, so the next machine is one click. Check the page shows the code the command printed, and click Approve. It is the only step that needs you. A machine that already has a credential sets up more apps with no approval.
  4. The app is configured from what setup 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_...
    Sign-in then works on http://127.0.0.1. The app is a live app from the start, so going to production is adding your real callback (the list replaces the old one, so repeat the ones to keep):
    wicket apps update live_... --redirect-uri http://127.0.0.1:3000/callback \
      --redirect-uri https://app.example.com/callback

/llms.txt is this guide written for agents: the values, the flow, ID-token checks in Python, TypeScript, Go and Rust, and the mistakes to avoid.

The same calls with curl

For an agent that doesn't install the CLI.

ISSUER=https://login.wicketauth.com

curl -s -X POST $ISSUER/cli/start -H 'Content-Type: application/json' \
  -d '{"client_label": "my laptop"}'
# {"grant": "...", "user_code": "BCDF-GHJK", "verification_uri": "https://login.wicketauth.com/cli",
#  "verification_uri_complete": "https://login.wicketauth.com/cli?code=BCDF-GHJK", "expires_in": 600, "interval": 5}

Nothing is mailed. Show the person verification_uri_complete and the user_code: they open the link, sign in with their email if that browser isn't signed in yet, check the page shows the same code, and click Approve. Meanwhile, poll every interval seconds:

curl -s -X POST $ISSUER/cli/poll -H 'Content-Type: application/json' \
  -d '{"grant": "..."}'
# 400 {"error": "authorization_pending"} until they approve, then once:
# 200 {"credential": "wkt_live_...", "email": "you@example.com", "expires_after_idle_days": 90}

Other answers end the grant: access_denied (they clicked Deny), expired_token (10 minutes passed, or the credential was already handed out); slow_down means poll less often. Keep the credential like a password. Then register the app:

curl -s -X POST $ISSUER/api/apps -H "Authorization: Bearer wkt_live_..." \
  -H 'Content-Type: application/json' \
  -d '{"name": "My app", "redirect_uris": ["http://127.0.0.1:3000/callback"]}'
# 201 {"client_id": "live_...", "name": "My app", "redirect_uris": [...]}

What it is

Identifierthe person's email address
Sign-ina one-time link, by email
ProtocolOpenID Connect shaped: Authorization Code with PKCE (S256), RS256 ID tokens, a published JWKS
Clientspublic only, PKCE required. No client secrets exist.
Tokensone ID token per sign-in, valid for 10 minutes

How a sign-in goes

  1. Your app sends the browser to Wicket's sign-in page.
  2. The person types their email address, and Wicket mails them a link.
  3. They open the link and press Continue. Wicket sends the browser back to your app with a one-time code.
  4. Your app trades the code, with its PKCE verifier, for an ID token whose subject is their address.

1. Register your app

With the CLI or curl, as above, or sign in to the dashboard (login.wicketauth.com/dashboard) with your email address and create an app. The two are the same apps. Your client_id is live_ and 20 characters.

An app is a name and a list of redirect URIs. Wicket compares the redirect_uri of each request with that list exactly, character for character: no prefixes, no wildcards. There is no client secret.

2. The values your OIDC library needs

SettingValue
Issuerhttps://login.wicketauth.com
Discoveryhttps://login.wicketauth.com/.well-known/openid-configuration
Authorization endpointhttps://login.wicketauth.com/authorize
Token endpointhttps://login.wicketauth.com/token
JWKShttps://login.wicketauth.com/jwks.json
Client authenticationnone (a public client)
Response typecode
PKCErequired, S256 only
Scopesopenid email
ID token signatureRS256
ID token type (header typ)wicket-id+jwt

The issuer is exactly https:// and the host: no trailing slash. Pin it byte for byte.

Most OIDC libraries work with just these values: Wicket reads the token request form-encoded, as they send it, and its ID token carries back the nonce you sent. Auth.js needs two more settings, below. And check the ID token's typ, wicket-id+jwt: most libraries don't check it at all, so check it yourself, as below. Two reject every Wicket ID token until told to accept it: Spring Security (Java) and Rust's openidconnect.

Auth.js (NextAuth v5)

Auth.js needs two settings beyond the issuer. Wicket has no userinfo endpoint, and Auth.js refuses a discovered server without one unless token is set. It also sends the client_id in a Basic header unless the client says none, and 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.

// 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"],
    },
  ],
});

Register https://<your host>/api/auth/callback/wicket as the redirect URI. Auth.js reads the ID token straight from /token and checks its claims itself; session.user.email is the person's address.

A browser-only app needs no server. A single-page app can run the whole flow in the browser, the code exchange included: discovery, the JWKS and the token endpoint answer requests from any origin. Wicket keeps no session, so a silent sign-in (prompt=none) always comes back with error=login_required: turn silent renew off (in oidc-client-ts, automaticSilentRenew: false) and, when your session ends, send the person through the form again.

3. The flow, step by step

Send the person to Wicket

Make a random PKCE verifier (43 to 128 characters of A-Z a-z 0-9 - . _ ~) and a random state, and keep both in the person's session, with a random nonce if you send one. The challenge is the verifier's SHA-256, base64url without padding. Then redirect the browser to:

https://login.wicketauth.com/authorize
  ?client_id=live_...
  &redirect_uri=https://app.example.com/callback
  &response_type=code
  &scope=openid%20email
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256
  &state=<state>
  &nonce=<nonce>

Wicket shows the form, the person enters their address, and Wicket mails them a link. The link works once, for 15 minutes.

Take the code

The link opens a page with one Continue button, so a mail scanner that fetches the link doesn't use it up. Pressing Continue sends the browser to your redirect URI:

https://app.example.com/callback?code=...&state=...

Check that state is the one you stored. The code works once, for 5 minutes.

A callback with no pending sign-in. The link works only in the browser that started the sign-in (see where the link opens). Opened on another device, or in a mail app's own browser, it reaches your callback where no pending sign-in matches its state. Most libraries throw an error 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 from here.

Trade the code for an ID token

POST https://login.wicketauth.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<code>
&client_id=live_...
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&code_verifier=<verifier>

The same fields as a JSON object, with Content-Type: application/json, work too.

The answer:

{ "access_token": "...", "id_token": "eyJ...", "token_type": "Bearer", "expires_in": 600 }

The ID token is what you sign the person in with. The access_token is there because OAuth requires one: Wicket has no API for it to call, and nothing accepts it.

Errors are OAuth's (RFC 6749 §5.2): {"error": "<code>", "error_description": "<why>"}, 400 with invalid_request (a parameter missing or malformed, a verifier that isn't 43-128 allowed characters), invalid_grant (the code unknown, used or expired, or a wrong verifier, redirect_uri or client_id for it) or unsupported_grant_type, and 401 with invalid_client for an unknown client_id.

An authorization request without an S256 code_challenge comes back to your redirect URI with ?error=invalid_request&error_description=...&state=..., and one with prompt=none with ?error=login_required&.... An unknown client_id or unregistered redirect_uri never redirects: Wicket shows an error page.

Verify the ID token

Check all of these, with any JWT library:

In Python, with PyJWT:

import jwt  # PyJWT

ISSUER = "https://login.wicketauth.com"
CLIENT_ID = "live_..."
jwks = jwt.PyJWKClient(ISSUER + "/jwks.json")

def verify(id_token: str) -> dict:
    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)
    return jwt.decode(id_token, key.key, algorithms=["RS256"],
                      audience=CLIENT_ID, issuer=ISSUER)

user = verify(id_token)["sub"]   # "alice@example.com"

Spring Security (Java)

Spring Security's oauth2Login() checks typ itself and accepts only JWT. Without the bean below, 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. It works on 6.4 to 7.1:

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<ClientRegistration> wicketIdTokenDecoderFactory() {
    Map<String, JwtDecoder> 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, register Wicket as 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

The openidconnect crate (4.x) 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)?;

Start your own session

The ID token is proof that the person controls the address, and it expires in 10 minutes. There are no refresh tokens. Start your app's own session from it, as long as you like, and when that session ends, send the person through Wicket again.

4. What's in the token

ClaimValue
subthe email address, normalised: trimmed and lowercased. +tags and dots are kept.
emailthe same address
email_verifiedalways true: the person opened the link
issthe issuer
audyour client_id
iat, expissued at, and 10 minutes later, in Unix seconds
noncethe nonce your request sent; absent if it sent none

The subject is the same in every app that uses Wicket, and a person who changes address is a new subject. Key your users by sub knowing both.

5. Development, staging and production

One app covers development and production. Wicket accepts http://127.0.0.1, http://[::1] and http://localhost redirect URIs, so the app you register while building signs people in in production once you add your real callback.

Want staging? Register a second app, with your staging callback, on the same issuer. It gets its own client_id, and its tokens are for that client_id only, so neither app accepts the other's.

6. Good to know

7. Managing apps from code

The dashboard's operations are also a JSON API. The CLI uses it, and so can your code:

CallBodyAnswer
GET <issuer>/api/apps{"apps": [...]}, yours
POST <issuer>/api/apps{"name", "redirect_uris": [...]}201, the app
GET <issuer>/api/apps/{client_id}the app
PUT <issuer>/api/apps/{client_id}{"name", "redirect_uris": [...]}the app; replaces both
DELETE <issuer>/api/apps/{client_id}204; its sign-ins stop at once
POST <issuer>/api/apps/{client_id}/checkout{"plan": "starter"} or {"plan": "pro"}{"url"}: Stripe Checkout for that plan
DELETE <issuer>/api/credential204; revokes the credential that sent it

An app is {"client_id", "name", "redirect_uris"}. Every call sends Authorization: Bearer wkt_live_…: the credential an approval in a signed-in browser grants, from wicket setup or /cli/start and /cli/poll. Nothing else is accepted, the dashboard's sign-in included. Errors are {"error": "..."}: 401 for a missing, revoked or expired credential, and 404 for an app that isn't yours, the same as one that doesn't exist.

Registering an app, by POST /api/apps as anywhere else, means you accept Wicket's terms.

The credential is your own key for managing your apps. It signs nobody in to anything, Wicket's dashboard included, and no app ever sees it. A person holds at most 10 at once, and one unused for 90 days expires. The dashboard's CLI credentials page lists and revokes them.