Dashboard|

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()
ParameterRequiredMeaning
response_typeYesAlways code.
client_idYesYour app's client ID.
redirect_uriYesOne of your registered addresses, exactly.
scopeYesPermissions, separated by spaces. Each must be one your app registered.
code_challengeYesThe PKCE challenge.
code_challenge_methodNoS256, which is also the default and the only method.
stateRecommendedReturned to you unchanged. Check it to make sure the answer belongs to the request you started.

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:

  1. Check that state equals the value in the session. If it does not, stop.
  2. If there is an error, show the person what happened. Do not retry automatically.
  3. Otherwise exchange the code for tokens. The code works once and expires after 5 minutes.
errorMeaning
access_deniedThe person clicked Cancel.
invalid_scopescope is missing, names a permission that does not exist, or asks for one your app did not register.
invalid_requestThe PKCE challenge is missing or malformed, or state is not printable text.
unsupported_response_typeresponse_type is not code.

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.