Endpoints

Everything a client app calls: one page in the browser (/authorize) and three server-to-server endpoints.

EndpointAddressCalled from
GET /authorizehttps://sso.sentratechnology.comThe user’s browser
POST /oauth/tokenhttps://api.sso.sentratechnology.comYour server
GET /oauth/userinfohttps://api.sso.sentratechnology.comYour server
GET /.well-known/jwks.jsonhttps://api.sso.sentratechnology.comYour server

Lifetimes

ItemLifetime
code60 seconds, single use.
Access token15 minutes (expires_in: 900).
Refresh tokenNone. Your app’s session decides how long users stay signed in.
Sentra session24 hours, not extended by activity.

GET /authorize

Send the user’s browser to this page to start a sign-in.

ParameterRequiredMeaning
response_typeYesAlways code.
client_idYesThe App ID from the console (app_…).
redirect_uriYesMust exactly match one of the registered Redirect URIs.
stateYesA random value from your app, at most 512 characters. Returned unchanged.
code_challengeNoPKCE: the SHA-256 of the code_verifier, base64url without =. 43–128 characters.
code_challenge_methodWith code_challengeS256 only.
promptNoselect_account, login, consent or none.
max_ageNoSeconds. Ask the user to sign in again if their Sentra session is older than this.

What each prompt value does:

ValueMeaning
select_accountAlways show the account chooser.
loginAsk the user for their password again.
consentAsk for consent again, even if it was given before.
noneShow no screens. If sign-in or consent is needed, Sentra returns an error.

On success, Sentra sends the browser to your Redirect URI:

https://api.belajar.contoh.id/auth/sso/callback?code=Qm8xT2...&state=r7Kx2vQ9mT4w...

When the request is denied or invalid, Sentra returns error with the same state:

https://api.belajar.contoh.id/auth/sso/callback?error=access_denied&state=r7Kx2vQ9mT4w...
When client_id or redirect_uri doesn’t match, the app is deactivated, or state is missing, Sentra redirects nowhere and shows an Invalid link page. The full list is in Error codes.

POST /oauth/token

Exchange the code for an access token and the user’s data. Send the parameters in the body (application/x-www-form-urlencoded or JSON), not in the URL.

Authenticate your app with HTTP Basic (app_id:client_secret), or with client_id and client_secret in the body. Use one, not both.

ParameterRequiredMeaning
grant_typeYesAlways authorization_code.
codeYesThe code from the callback.
redirect_uriYesThe same value you sent to /authorize.
code_verifierWith code_challengeThe original PKCE value. Don’t send it if /authorize didn’t use PKCE.
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"

A 200 response, with Cache-Control: no-store:

{
  "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"]
  }
}

The user object is explained in User data. Requests to this endpoint are rate-limited per IP address.

GET /oauth/userinfo

Get fresh user data while the access token is valid. POST is accepted too.

curl "$SSO_API_URL/oauth/userinfo" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

A 200 response holds the same user object, without a wrapper:

{
  "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"]
}

This endpoint answers 401 invalid_token when the token has expired, the user’s account is deactivated, or your app is deactivated.

GET /.well-known/jwks.json

The public keys for checking an access token’s signature yourself. You don’t need them if you only use the user from /oauth/token.

curl "$SSO_API_URL/.well-known/jwks.json"
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "2026-11",
      "n": "5YjVAn4Ogke3VoIthANrR0AV0xhpU_IZcWArYo5_lf2Q...",
      "e": "AQAB"
    }
  ]
}

The response may be cached for 5 minutes. When the key changes, the old key stays in the list for a while, so pick the key by the kid in the token header.

The access token is an RS256 JWT with these claims:

ClaimContent
issSentra’s API address.
subThe user’s sentra_id.
audYour App ID. Reject tokens with another aud.
client_idYour App ID.
iat, nbf, expIssued at, not before, and expiry (15 minutes).
jtiThe token’s unique ID.