Everything, on
one page.
Read top-to-bottom, or jump via the sidebar. Ctrl+F searches the whole reference at once.
Introduction
Sign in with Chirp is standard OpenID Connect — with two differences from Google / Auth0 / Clerk: you never receive the user’s email, and the user ID you get (the sub) is unique to your app.
That’s the whole integration model. Register an app, drop in any standards-compliant OIDC client, and you get back a signed ID token whose sub is stable per user, scoped to your app, and carries no email. Everything else — how the user actually signs in, what device they use, how they recover access — is the user’s side, and Chirp handles it. You never have to reason about it to ship.
Getting access
Fully self-serve — no waitlist, no approval step. Sign in with an email link or a passkey, or choose Create an account with a passkey. A passkey account shows its account ID and recovery codes once, when you create it: save them. Then register your first app in the dashboard. Questions: support@chirpauth.com.
No operator setup is needed. The dashboard is where you register apps, edit callback URLs, and permanently retire apps when you are finished.
Quickstart
Required reading: it’s standard OIDC plus the two differences. Register an app, drop in any OIDC client, exchange the code — you get a token whose sub is per-app and which carries no email. Nothing about how the user signs in, what tier they’re on, or how they recover access enters your code. (Needs a developer account — see Getting access.)
/dashboard → New app name some-ecommerce-site.com redirect_uri https://some-ecommerce-site.com/auth/cb → client_id cs_dev_7f3a09c2… (a public PKCE client — no secret to keep)
Add more redirect URIs later on the app’s dashboard page. Client ids are cs_dev_… or cs_live_… — the prefix tells you the environment.
GET https://signin.chirpauth.com/.well-known/openid-configuration
3 · Add the “Sign in with Chirp” button (see integrate: web) and exchange the returned code at /token. Done.
PKCE is required; nonce is optional. Every /authorize request must send code_challenge with code_challenge_method=S256; a request without PKCE is refused, with or without a nonce, by redirecting back to your redirect_uri with error=invalid_request and an error_description that says what to send. If you also send a nonce, the ID token echoes it and you must check it matches. If you don’t, the ID token has no nonce claim. OIDC SPA libraries such as oidc-client-ts work in their default configuration.
OIDC reference
Authorization Code flow with PKCE. All responses JSON; all tokens signed RS256.
{
"issuer": "https://signin.chirpauth.com",
"authorization_endpoint": ".../authorize",
"token_endpoint": ".../token",
"jwks_uri": ".../jwks.json",
"scopes_supported": ["openid"],
"response_types_supported": ["code"],
"code_challenge_methods_supported": ["S256"],
"grant_types_supported": ["authorization_code",
"client_credentials",
"urn:ietf:params:oauth:grant-type:device_code"]
}grant_type=authorization_code
&code=<one-time>&redirect_uri=https://…/auth/cb
&client_id=cs_dev_7f3a…&code_verifier=<pkce>
→ { "id_token":"<jwt>", "access_token":"…",
"token_type":"Bearer", "expires_in":43200 }That is a public app: PKCE alone, no secret. A confidential app (registered with a secret) must also authenticate here with exactly one of HTTP Basic (client_secret_basic) or client_secret in the form (client_secret_post); without it the exchange is 401 invalid_client.
Machine tokens: client_credentials
Authorization: Basic base64(client_id:client_secret)
grant_type=client_credentials
&audience=<client_id of the service you will call>
→ { "id_token":"<jwt>", "token_type":"Bearer",
"expires_in":3600 }RFC 6749 §4.4, for a confidential app acting as itself, with no person signing in: a server calling another service built on Chirp. Authenticate as above (HTTP Basic or client_secret in the form). The answer’s id_token is a machine token; send it to that service as Authorization: Bearer. It has no refresh: mint a new one when it expires. audience names the service’s own client id, and the token is made for it alone: its aud is that service, and its sub is your app’s id there. An audience that is not a registered client is 400 invalid_target. The service verifies it as it verifies an ID token (RS256 by kid from /jwks.json, iss, exp, aud its own client id), except that its header typ is chirp-machine+jwt, not chirp-id+jwt, and it carries act: "machine", which the service requires. Without audience you get the older shape, whose aud is your own app; Chirp is retiring it. The service’s docs say which it accepts.
To get one, create a machine client on the dashboard (Register new app, then Create machine client). You approve it with your passkey, and its secret is shown once; rotate it from the app’s page.
Devices without a browser: device_code
client_id=cs_dev_7f3a…&scope=openid
→ { "device_code":"…", "user_code":"BCDF-GHJK",
"verification_uri":"https://…/device",
"verification_uri_complete":"https://…/device?user_code=BCDF-GHJK",
"expires_in":900, "interval":5 }grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<device_code>&client_id=cs_dev_7f3a…
→ { "id_token":"<jwt>", "access_token":"…",
"token_type":"Bearer", "expires_in":43200 }RFC 8628, for a CLI or other device that can’t open a browser, signing in a person. Only a public app may use it, and the scope can’t include chirp.control. Show the person user_code and verification_uri (or verification_uri_complete, as a link or QR code); they open it on any device, sign in, and approve. Meanwhile poll /token with the device_code, waiting interval seconds between polls. Until they approve, the answer is 400 authorization_pending; polling too fast is slow_down, so add 5 seconds to your interval; access_denied means they refused, and expired_token that the codes ran out after 15 minutes, so start again. Once approved, the next poll gets the ID token, which you verify as any other. It has no nonce claim: the device sends none, and the device_code ties the token to your request instead. The device_code is single use.
?id_token_hint=<the id_token> &post_logout_redirect_uri=https://…/signed-out &state=<opaque> &client_id=cs_dev_7f3a…
RP-initiated logout ends the person’s Chirp session on this browser and sends them to post_logout_redirect_uri, which must exactly match one registered under After sign-out on your app’s dashboard page (kept apart from redirect URIs, so it never receives sign-in codes). Pass the ID token as id_token_hint; an expired one is fine. Send your app’s client_id too: a post_logout_redirect_uri needs one of the two to say which app it belongs to, so without a hint it is required, and with both they must name the same app. Without a hint, or if it names someone else, Chirp asks the person before signing out. Ending your own app session is up to you, and other apps keep theirs.
token=<access_token>&client_id=cs_dev_7f3a… → 200
RFC 7009. Revokes the access_token from /token, so UserInfo stops accepting it; authenticate as you do at /token. ID tokens are self-contained and cannot be revoked — they end at exp — so revoking one answers unsupported_token_type.
Sessions: no refresh tokens
Chirp issues no refresh tokens and does not offer offline_access. A sign-in answers one question, who this is, and the answer (sub) never changes, so there is nothing to refresh. Validate the ID token, then start your own app session and give it whatever lifetime suits your app; the ID token’s 12-hour exp limits how long you may accept the token itself, not your session.
When your session ends, or you want to re-check that the person is still there, send them through sign-in again. While their Chirp session on that browser is alive (up to 30 days, ending sooner after 14 days unused or when they sign out) that is one click on Continue as …, with no email link or passkey. A token that outlives the person’s presence would be a standing credential linking them to your app; Chirp deliberately does not mint one.
/authorize also takes the OIDC prompt and max_age parameters, by GET or a form POST. prompt=none never shows a page: it returns a code if the person is signed in and has approved your app before, otherwise error=login_required or consent_required. prompt=login asks them to sign in again. prompt=select_account shows the accounts signed in on this browser so the person can pick one or add another; send it from your “Switch account” button. max_age=N asks them to sign in again if their last sign-in is older than N seconds, and adds auth_time to the ID token; check it.
Account deletion webhook
When someone who signed in to your app deletes their Chirp account, Chirp tells your app so you can delete their data. Register an HTTPS URL under Account deletion webhook on your app’s dashboard page (or POST /control/apps/set-deletion-webhook with {"client_id", "deletion_webhook_url"}). Chirp then POSTs one signed event per sub your app knows the person by, naming them by that sub and nothing else. deleted_at is the start of the UTC day of the deletion, not its exact second. A person your app knows under several subs (they used it as several personas) gets one event per sub, each sent at its own random time within a day, so the events don’t tell your app the subs are one person. A platform service granted chirp.root_resolve is also told about each person whose sub at another app it resolved through POST /control/root-for-sub: the event goes to the service’s own webhook, with aud and client_id its client ID and sub the sub it resolved.
The same URL gets people’s answers to the messages your app sends with POST /messages, as events signed and verified the same way: a message.reply (with in_reply_to, the id POST /messages answered, and subject and body) or a message.notice_action (with in_reply_to and action). sub is the sub your app addressed the person by, and event_id is the reply’s id, so dedupe on it. A confidential client sets its URL itself with POST /messages/webhook {"url"}; answers to a message go to the client that sent it.
header { "alg": "RS256", "typ": "chirp-event+jwt", "kid": "event_…" }
claims { "type": "user.deleted",
"sub": "sub_…", // the sub your app received
"client_id": "cs_live_…", "aud": "cs_live_…",
"deleted_at": 1792627200, // the UTC day, not the second
"event_id": "evt_…", "jti": "evt_…",
"iss": "https://signin.chirpauth.com", "iat": 1792640288 }The body is a JWT signed with a key published at /events/jwks.json — a separate key set from /jwks.json, so an ID-token verifier can never accept an event. Check typ, RS256, iss, that aud is your client ID, and that iat is at most 10 minutes old (each retry is re-signed, so a real delivery always is); then delete the data for sub and answer any 2xx. Every event carries the User-Agent ChirpAuth-Webhooks/1 (+https://signin.chirpauth.com/docs#deletion-webhook); if a firewall in front of your app filters requests (an AWS WAF managed rule set, say), allow it.
import time, jwt
ISSUER = "https://signin.chirpauth.com"
KEYS = jwt.PyJWKClient(ISSUER + "/events/jwks.json")
def on_chirp_event(body: bytes, client_id: str):
token = body.decode()
if jwt.get_unverified_header(token).get("typ") != "chirp-event+jwt":
raise ValueError("not a Chirp event")
event = jwt.decode(token, KEYS.get_signing_key_from_jwt(token).key,
algorithms=["RS256"], audience=client_id, issuer=ISSUER,
leeway=60, options={"require": ["iss", "aud", "iat", "jti"]})
if not time.time() - 600 <= event["iat"] <= time.time() + 60:
raise ValueError("stale event") # a replay; real retries are re-signed
if event["type"] == "user.deleted":
delete_user_data(event["sub"], event["event_id"]) # idempotentDelivery is at-least-once: deduplicate on event_id, which stays the same across retries (each retry is re-signed with a fresh iat). Anything but a 2xx within 5 seconds is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, then daily — 10 attempts over about 4 days — after which the event is marked failed and shown on your dashboard. Once your endpoint is fixed, press Send failed events again above the failed events on your app’s dashboard page: each is sent again with a fresh set of attempts and the same event_id. (A registrar or operator does the same with POST /control/apps/retry-deletion-events and {"client_id"}.) If your app has no webhook URL, deletions are recorded as undeliverable and shown on the dashboard; registering a URL later delivers that backlog. Events are kept 90 days.
Integrate: web
This complete local example uses Rust and openidconnect 4.0.1. Install Rust and Cargo first. In the dashboard, register http://127.0.0.1:4178/auth/cb as your app’s redirect URI.
The example is the files below; there is no archive. Download them all into a new directory with these commands (each address also opens its file in the browser):
mkdir chirp-web && cd chirp-web curl -fsS --create-dirs https://signin.chirpauth.com/quickstart/.cargo/audit.toml -o .cargo/audit.toml curl -fsS --create-dirs https://signin.chirpauth.com/quickstart/Cargo.toml -o Cargo.toml curl -fsS --create-dirs https://signin.chirpauth.com/quickstart/Cargo.lock -o Cargo.lock curl -fsS --create-dirs https://signin.chirpauth.com/quickstart/src/main.rs -o src/main.rs curl -fsS --create-dirs https://signin.chirpauth.com/quickstart/.env.example -o .env.example curl -fsS --create-dirs https://signin.chirpauth.com/quickstart/.gitignore -o .gitignore curl -fsS --create-dirs https://signin.chirpauth.com/quickstart/README.md -o README.md cp .env.example .env
Edit .env: replace CHIRP_CLIENT_ID with the client ID from your dashboard. Then run:
cargo run --locked
Open http://127.0.0.1:4178 and choose Sign in with Chirp. The callback displays OIDC verified and your app-specific sub. Refreshing that callback must fail; start a new login from the app’s home page.
The example generates and stores state, nonce, and a PKCE verifier in a one-use transaction bound to an HttpOnly browser cookie. The SDK validates the signed ID token and checks that UserInfo returns the same subject. Ordinary access tokens authorize only UserInfo; they cannot call Chirp control APIs. This example does not retain tokens or create a persistent app session.
For production, use HTTPS and Secure cookies, shared transaction storage for multiple instances, and your own app session after validation. See the complete instructions and limits. Any standard OIDC SDK can implement this same flow.
Finish and clean up
Open the app in your dashboard, type its client ID, and choose Permanently retire app. The dashboard confirms that the app is retired. This cannot be undone and prevents future sign-ins and token exchanges: /authorize then answers that the client_id was retired; sessions your app already created follow your app’s own expiry policy. If recent authentication is required, sign out from your Chirp account page and sign in again.
After retiring all owned apps and cancelling any subscription, you can delete your account from account management. Download your current Chirp account data from account export.
Integrate: iOS
Use ASWebAuthenticationSession with a claimed HTTPS callback (Universal Link). Never embed a WebView — Apple requires the system browser for OAuth, and so do we.
let session = ASWebAuthenticationSession(
url: authorizeURL, callbackURLScheme: nil
) { callback, error in
guard let code = callback?.queryItem("code") else { return }
exchangeForToken(code) // POST /token + PKCE
}
session.prefersEphemeralWebBrowserSession = false
session.start()Integrate: Android
Chrome Custom Tabs with an App Link callback. AppAuth handles PKCE and the token exchange.
val req = AuthorizationRequest.Builder(
config, CLIENT_ID, ResponseTypeValues.CODE,
Uri.parse("https://…/auth/cb"))
.setScope("openid").build() // PKCE auto-added
service.performAuthorizationRequest(req, ok, cancel)Declare the callback host with android:autoVerify="true" so Android opens it without a chooser.
Test tokens
Test your token handling before anyone signs in. On your app’s page in the dashboard, Mint a test token gives you a real RS256-signed ID token for a made-up user of that app. Its sub starts with test: (test:alice, or leave it blank for a random one), its aud is your client id, and it expires in 15 minutes. If your app sends a nonce to /authorize, enter the one it expects and the token echoes it; leave it blank and the token has no nonce claim, as a real one has when your app sends none.
id_token eyJhbGciOiJSUzI1NiIs… issuer https://signin.chirpauth.com/test/tnt_… jwks https://signin.chirpauth.com/test/tnt_…/jwks.json
A test token is signed by your account’s own test key under that test issuer, never by Chirp’s production key. So your production verifier, which trusts https://signin.chirpauth.com, rejects it, and it can never stand in for a real user.
To accept it in a test environment, have your ID-token verifier trust the test issuer instead of https://signin.chirpauth.com, with the keys from the test issuer’s jwks.json. Build the verifier from those two, not from discovery: test users never sign in through a browser, so the test issuer has no authorization endpoint, and an OIDC client that loads full provider metadata won’t accept its discovery document. With the openidconnect crate the Rust example uses, that is CoreIdTokenVerifier::new_public_client with the key set from JsonWebKeySet::fetch_async.
Then hand the token to your app the way it gets a real ID token, and check it signs in the test: user. Mint another whenever one expires.
How it works
You can skip this whole section and still integrate. It’s reference for the curious: how the per-app sub is derived, how users actually sign in, and the upgrade path on the user’s side. None of it appears in your code — the token is the same no matter which of these a user is on.
Most identity providers hand every app the same stable id, so any two apps can compare lists and discover they share a user. Chirp never does that — the sub we give an app is derived, not stored:
sub = "sub_" + base64url(HMAC-SHA256(K,
"chirp-auth/pairwise-sub/v1" || 0x00 ||
u64be(len(client_id)) || client_id ||
u64be(len(id)) || id))
K = a 32-byte secret key only Chirp holds
id = the user's account id (for an Extended
account: the persona they sign in with)user_id = usr_9f3a (never leaves Chirp) some-ecommerce-site.com (cs_live_AAAA) → sub = sub_tocW0lhH…vsGc notes.hello.io (cs_live_BBBB) → sub = sub_V8fPyhJ3…RE3DI compare subs → no match. Can't tell it's one user.
The mapping is one-way: an app can’t reverse a sub back to the user’s id, and without K nobody can compute one user’s sub at another app — and apps never receive an email address at all. There is no email scope; Chirp keeps the address server-side. Request openid — every sign-in needs it, and it’s the only scope discovery lists. chirp.control and drive.* also exist, for Chirp’s own CLI and allowlisted Stackwell services; other apps are refused them, so discovery does not advertise them. Use sub as your app’s login identifier. Tokens never expose the account root, so separate personas cannot be linked through a root claim.
A sub depends on K and your client id, and every token names https://signin.chirpauth.com as its iss. Another provider, or your own self-hosted copy of Chirp, has its own key, its own client ids and its own iss. So when you move an app off chirpauth.com, every user’s sub changes, and there is no export that maps old subs to new ones. You can’t re-match users by email either, since your app never had it. To carry users across, keep both working for a while: once a user signs in with the new issuer, have them sign in with Chirp one more time and attach the new sub to the account their old one names. Store iss with sub, so the two never collide.
Users land on signin.chirpauth.com — the same page every Chirp app shares — and sign in one of two ways. You never see or choose which:
- Email link. A short-lived link to the address they signed up with. Nothing to remember, nothing to type.
- Passkey. A key pair bound to a device and a domain — the private half never leaves the device; Chirp stores only the public half. Signing in is a Face ID / Touch ID / PIN prompt, nothing to phish. Supported by iCloud Keychain, Google Password Manager, Windows Hello, and hardware keys (YubiKey).
Chirp Zero is the easy way in — an email-link account, no password, no setup. Chirp One is the user’s real passkey-secured account, reached as a contextual upgrade later, with recovery codes as a backup way in if they lose every passkey. This is purely the end user’s story: a developer never reasons about which tier a user is on. The ID token is identical either way — same shape, same per-app sub, no email. Don’t branch on it.
Troubleshooting
Every error page carries a reference id (e.g. 7Q3K-2M11-XZ22) and, for developers, a trace id. Include the reference id when you email support — it's the only handle we have, because we don't store who you are.