Endpoints
Everything a client app calls: one page in the browser (/authorize) and three server-to-server endpoints.
| Endpoint | Address | Called from |
|---|---|---|
GET /authorize | https://sso.sentratechnology.com | The user’s browser |
POST /oauth/token | https://api.sso.sentratechnology.com | Your server |
GET /oauth/userinfo | https://api.sso.sentratechnology.com | Your server |
GET /.well-known/jwks.json | https://api.sso.sentratechnology.com | Your server |
Lifetimes
| Item | Lifetime |
|---|---|
code | 60 seconds, single use. |
| Access token | 15 minutes (expires_in: 900). |
| Refresh token | None. Your app’s session decides how long users stay signed in. |
| Sentra session | 24 hours, not extended by activity. |
GET /authorize
Send the user’s browser to this page to start a sign-in.
| Parameter | Required | Meaning |
|---|---|---|
response_type | Yes | Always code. |
client_id | Yes | The App ID from the console (app_…). |
redirect_uri | Yes | Must exactly match one of the registered Redirect URIs. |
state | Yes | A random value from your app, at most 512 characters. Returned unchanged. |
code_challenge | No | PKCE: the SHA-256 of the code_verifier, base64url without =. 43–128 characters. |
code_challenge_method | With code_challenge | S256 only. |
prompt | No | select_account, login, consent or none. |
max_age | No | Seconds. Ask the user to sign in again if their Sentra session is older than this. |
What each prompt value does:
| Value | Meaning |
|---|---|
select_account | Always show the account chooser. |
login | Ask the user for their password again. |
consent | Ask for consent again, even if it was given before. |
none | Show 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...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.
| Parameter | Required | Meaning |
|---|---|---|
grant_type | Yes | Always authorization_code. |
code | Yes | The code from the callback. |
redirect_uri | Yes | The same value you sent to /authorize. |
code_verifier | With code_challenge | The 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:
| Claim | Content |
|---|---|
iss | Sentra’s API address. |
sub | The user’s sentra_id. |
aud | Your App ID. Reject tokens with another aud. |
client_id | Your App ID. |
iat, nbf, exp | Issued at, not before, and expiry (15 minutes). |
jti | The token’s unique ID. |