OAuth 2.0 / OIDC endpoints

External apps use the Authorization Code + PKCE flow for SSO. It is the only way to obtain application-bound JWTs.

There is no OAuth client_id. The client identifies itself with its access key everywhere:

• Browser redirects (/oauth/authorize, /oauth/logout) carry key_id=<key fingerprint> — the SHA-256 fingerprint of the DER-encoded public key, base64url without padding.
• Server-to-server calls (/oauth/token, /oauth/revoke) carry the public key itself, in the X-App-Public-Key header or an app_public_key field.

Authorization requests are sent to the UI browser endpoint configured as OAUTH_AUTHORIZATION_ENDPOINT (default http://localhost:3000/oauth/authorize):

GET {authViewUrl}/oauth/authorize?response_type=code&key_id=<key fingerprint>&redirect_uri=https%3A%2F%2Fhrm.example.com%2Fcallback&scope=openid%20profile%20email&state=<state>&nonce=<nonce>&code_challenge=<challenge>&code_challenge_method=S256

Logout redirects use the same identifier:

GET {authViewUrl}/oauth/logout?post_logout_redirect_uri=https%3A%2F%2Fhrm.example.com%2Fsigned-out&key_id=<key fingerprint>

The token endpoint is the API endpoint:

POST /api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
X-App-Public-Key: -----BEGIN PUBLIC KEY-----\nMIIB...\n-----END PUBLIC KEY-----

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

The presented key must belong to the same application as the authorization code or refresh token being exchanged — tokens survive key rotation but never cross applications.

Token response covering

The access_token, id_token, and refresh_token response fields are returned with a lightweight cvr1 AES-GCM cover derived from the access key public key supplied in X-App-Public-Key. External app backends must uncover those values with the same public key before JWT verification/use.

After uncovering, access and ID tokens are RS256 JWTs signed with the presented access key's private key. The JWT header kid equals the access key's public-key fingerprint and matches the key published by /api/v1/oauth/jwks?kid=<fingerprint>.

The redirect_uri and post_logout_redirect_uri are validated against the access key's Allowed URLs. The user's company is resolved server-side from the user's active memberships subscribed to the requested application — clients do not pick the company.

Allowed URLs

Every access key carries a list of Allowed URLs, set when the key is created on the support console's Access keys page. It is the only list the API will redirect a signed-in user to for requests made with that key.

Format — one URL per entry

The list is stored as text and split on whitespace or commas. Put each URL on its own line (or separate them with commas):

https://smartfarm-ui.caprover.truecode.africa
http://localhost:3005

Both forms parse to the same two entries:

https://smartfarm-ui.caprover.truecode.africa, http://localhost:3005

Each entry must be an absolute http:// or https:// URL with a host, and no query string and no #fragment. Trailing slashes are stripped on save.

Do not paste an escaped \n between URLs. If the backslash is lost in transit the list becomes a single glued entry such as https://smartfarm-ui.caprover.truecode.africa/nhttp://localhost:3005 — a syntactically valid URL, so it saves without error, but neither real origin is registered and every sign-in fails the return URL check. After creating the key, open it and confirm you see one URL per line.

How a redirect is matched

An incoming redirect_uri is allowed when some entry matches on both:

• Origin — exact. Scheme, host, and port must all be equal. Ports default to 443 for https and 80 for http, so https://app.example.com and https://app.example.com:443 are the same origin, while http://localhost:3005 and http://localhost:3000 are not.
• Path — prefix. The redirect path must equal the entry's path or sit below it. An entry with no path (path /) matches every path on that origin.

Registering the bare origin is usually what you want: it covers the callback, the post-logout URL, and any future route without needing a replacement key.

Local development

http:// and localhost are accepted — there is no special-casing that blocks them. To run a local build against a deployed Authfy, add your dev origin alongside the production one, matching the port your dev server actually uses:

https://smartfarm-ui.caprover.truecode.africa
http://localhost:3005

Be aware of what this means: anyone who can start an authorization request with that key_id can have the code delivered to a listener on their own machine. If that is not acceptable for a production application, create a separate development access key instead — with only the local origin in its Allowed URLs — and point the local .env at its public key.

Token creation rules

• GET and POST /api/v1/oauth/authorize create the authorization code.
• POST /api/v1/oauth/token (with grant_type=authorization_code or grant_type=refresh_token) returns the access token, ID token, and refresh token.
• The token endpoint requires the access key public key in X-App-Public-Key (or an app_public_key form/JSON field). The backend resolves the key to its application, confirms the key is usable and belongs to the same application as the code or refresh token, and signs the tokens with that key's private key (JWT header kid = the key's fingerprint).
• A key is usable only while it is ACTIVE, inside its optional startsAt/expiresAt window, and its application is ACTIVE. Expired or revoked keys stop working immediately — including verification of outstanding tokens they signed. Because an application can hold many keys, rotation is zero-downtime: create a replacement key, reconfigure the client, then revoke the old key.
• POST /api/v1/auth/login and POST /api/v1/auth/refresh do not accept X-App-Public-Key and never produce application JWTs.

The authfy npm package wires this whole flow — including PKCE, the token cover, silent refresh, and logout — into a Next.js app with two files.