Quickstart
Add "Sign in with Sentra" to your app. Sentra tells you who the user is; your app keeps control of sessions and roles.
1. Register your app
Open the console, create an app, then set the Redirect URI (the callback address on your server) and the login URL. Download the .env from the console and keep it on your server. The Client secret is shown only once.
SSO_BASE_URL=https://sso.sentratechnology.com
SSO_API_URL=https://api.sso.sentratechnology.com
SSO_APP_ID=app_9fk2mq7xlr4tzw8nb3vh5cyd
SSO_CLIENT_SECRET=sec_...
SSO_REDIRECT_URI=https://api.belajar.contoh.id/auth/sso/callbackhttps, except for localhost during development.2. Send the user to Sentra
Generate a random state value and a PKCE code_verifier, keep both in the user’s session, then redirect the user to /authorize.
https://sso.sentratechnology.com/authorize
?response_type=code
&client_id=app_9fk2mq7xlr4tzw8nb3vh5cyd
&redirect_uri=https://api.belajar.contoh.id/auth/sso/callback
&state=r7Kx2vQ9mT4w...
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256Examples for Laravel (in the redirect route) and Next.js (a server module):
$state = Str::random(40);
$verifier = Str::random(64);
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
$request->session()->put(['sentra_state' => $state, 'sentra_verifier' => $verifier]);
$url = config('services.sentra.base_url').'/authorize?'.http_build_query([
'response_type' => 'code',
'client_id' => config('services.sentra.app_id'),
'redirect_uri' => config('services.sentra.redirect_uri'),
'state' => $state,
'code_challenge' => $challenge,
'code_challenge_method' => 'S256',
]);// lib/sentra.ts
import { createHash, randomBytes } from "node:crypto";
export type SentraUser = {
sentra_id: string;
name: string;
picture: string | null;
credential: string;
roles: string[];
user_types: string[];
};
export function startSignIn() {
const state = randomBytes(24).toString("base64url");
const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const url = new URL("/authorize", process.env.SSO_BASE_URL);
url.search = new URLSearchParams({
response_type: "code",
client_id: process.env.SSO_APP_ID!,
redirect_uri: process.env.SSO_REDIRECT_URI!,
state,
code_challenge: challenge,
code_challenge_method: "S256",
}).toString();
return { url: url.toString(), state, verifier };
}code_challenge, Sentra requires the matching code_verifier when you exchange the code. PKCE is recommended for every app.Optional extra parameters:
| Parameter | Meaning |
|---|---|
prompt=select_account | Always show the account chooser. |
prompt=login | Ask the user for their password again. |
prompt=consent | Ask for consent again, even if it was given before. |
prompt=none | Show no screens. If the user isn’t signed in or hasn’t consented, Sentra returns error=login_required or error=consent_required. |
max_age=<seconds> | Ask the user to sign in again if their Sentra session is older than this. |
3. Exchange the code on your server
Sentra returns code and state to your Redirect URI. Check that state matches the one you stored, then exchange the code from your server within 60 seconds. A code works only once.
curl -X POST "$SSO_API_URL/oauth/token" \
-u "$SSO_APP_ID:$SSO_CLIENT_SECRET" \
--data-urlencode grant_type=authorization_code \
--data-urlencode code="$CODE" \
--data-urlencode redirect_uri="$SSO_REDIRECT_URI" \
--data-urlencode code_verifier="$CODE_VERIFIER"$state = $request->session()->pull('sentra_state');
abort_unless($state && hash_equals($state, (string) $request->query('state')), 403);
$response = Http::asForm()
->withBasicAuth(config('services.sentra.app_id'), config('services.sentra.client_secret'))
->post(config('services.sentra.api_url').'/oauth/token', [
'grant_type' => 'authorization_code',
'code' => $request->query('code'),
'redirect_uri' => config('services.sentra.redirect_uri'),
'code_verifier' => $request->session()->pull('sentra_verifier'),
])
->throw();
$user = $response->json('user');// lib/sentra.ts (continued)
export async function exchangeCode(code: string, verifier: string): Promise<SentraUser> {
const basic = Buffer.from(`${process.env.SSO_APP_ID}:${process.env.SSO_CLIENT_SECRET}`).toString("base64");
const res = await fetch(`${process.env.SSO_API_URL}/oauth/token`, {
method: "POST",
headers: { Authorization: `Basic ${basic}` },
body: new URLSearchParams({
grant_type: "authorization_code",
code,
redirect_uri: process.env.SSO_REDIRECT_URI!,
code_verifier: verifier,
}),
});
if (!res.ok) throw new Error(`Sentra token exchange failed: ${res.status}`);
const { user } = (await res.json()) as { user: SentraUser };
return user;
}error=access_denied with the same state.4. Read the user data
The response contains the user’s identity. The access token lasts 15 minutes, and you don’t need to store it if you only need sign-in.
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
"token_type": "Bearer",
"expires_in": 900,
"user": {
"sentra_id": "8f3a1c52-7d0e-4b6a-9c21-5e7f0a3d9b14",
"name": "Aisyah Rahmawati",
"picture": "https://api.sso.sentratechnology.com/files/8f3a1c52.jpg",
"credential": "aisyah.rahmawati@contoh.id",
"roles": ["editor"],
"user_types": ["umum"]
}
}Need fresh data while the token is valid? Call userinfo:
curl "$SSO_API_URL/oauth/userinfo" \
-H "Authorization: Bearer $ACCESS_TOKEN"sentra_id as your user key. credential holds the email when the account has one, otherwise the username, so don’t assume it’s always an email address and don’t link accounts on it. roles holds the roles an admin gave the user in your app, and user_types holds the user types.5. Create a session in your app
Find or create the user by sentra_id, decide their role, then start your app’s session. You decide how long it lasts; Sentra issues no refresh token. Laravel example:
$account = User::updateOrCreate(
['sentra_id' => $user['sentra_id']],
['name' => $user['name']],
);
Auth::login($account);
$request->session()->regenerate();