Authorize a user
Send a person to Cencori's approval screen and handle the redirect back.
To ask for access, send the person's browser to https://cencori.com/oauth/authorize.
1. Create a PKCE verifier and a state
Before redirecting, create two random values and keep them in the person's session on your server:
- a code verifier: 43 to 128 characters from
A-Z a-z 0-9 - . _ ~ - a state: any random string, up to 512 characters
The code challenge is the SHA-256 of the verifier, base64url-encoded without padding.
import { createHash, randomBytes } from "node:crypto";
const codeVerifier = randomBytes(32).toString("base64url");
const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
const state = randomBytes(16).toString("base64url");
// Save codeVerifier and state in the user's session.2. Redirect to Cencori
const url = new URL("https://cencori.com/oauth/authorize");
url.searchParams.set("response_type", "code");
url.searchParams.set("client_id", process.env.CENCORI_CLIENT_ID);
url.searchParams.set("redirect_uri", "https://app.example.com/oauth/callback");
url.searchParams.set("scope", "organization:read projects:write api_keys:write");
url.searchParams.set("state", state);
url.searchParams.set("code_challenge", codeChallenge);
url.searchParams.set("code_challenge_method", "S256");
// Redirect the browser to url.toString()3. The person decides
If the person is not signed in to Cencori, they sign in first and come back to the approval screen. The screen shows your app's name and each permission you asked for.
They choose one organization. Only organizations they own or administer are offered. If you ask for api_keys:write, only organizations they own can be chosen, because creating API keys is the owner's right in Cencori.
Approving the same app again for the same organization replaces the permissions it had.
4. Handle the redirect
Cencori sends the browser to your redirect_uri.
Approved:
https://app.example.com/oauth/callback?code=…&state=…
Declined or failed:
https://app.example.com/oauth/callback?error=access_denied&error_description=…&state=…
In your callback:
- Check that
stateequals the value in the session. If it does not, stop. - If there is an
error, show the person what happened. Do not retry automatically. - Otherwise exchange the
codefor tokens. The code works once and expires after 5 minutes.
If the client_id is unknown or the redirect_uri is not registered, Cencori shows an error page and does not redirect. An address it cannot trust is never sent anything.

