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/callback
The Redirect URI must match the registered one exactly, including scheme, port and path. Use https, 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=S256

Examples 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',
]);
If you send a code_challenge, Sentra requires the matching code_verifier when you exchange the code. PKCE is recommended for every app.

Optional extra parameters:

ParameterMeaning
prompt=select_accountAlways show the account chooser.
prompt=loginAsk the user for their password again.
prompt=consentAsk for consent again, even if it was given before.
prompt=noneShow 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"
Never put the Client secret in browser code. If the user denies access, Sentra returns 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"
Use 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();