Error codes

The errors a client app can meet: on the /authorize page, at your Redirect URI when the user comes back, and from the /oauth/token and /oauth/userinfo endpoints.

When Sentra can’t verify the app or its Redirect URI, the user is sent nowhere. Sentra shows an Invalid link page with the client_id, the redirect_uri and the error code. This stops Sentra from being used to send users to an unregistered address.

CodeCauseWhat to do
invalid_clientThe client_id is unknown.Check SSO_APP_ID.
invalid_redirect_uriThe redirect_uri doesn’t exactly match a registered Redirect URI.Match the scheme, host, port, path and query, or register that URI in the console.
application_inactiveA Sentra admin deactivated the app.Contact a Sentra admin.
state_requiredstate is empty or longer than 512 characters.Always send a random state from your app.

Because nothing is redirected, your app receives nothing. Only the user sees these errors, so test your sign-in link whenever you change a Redirect URI.

At your Redirect URI

Once the app and Redirect URI are verified, other errors are sent back to your Redirect URI with the same state:

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

Check state first, as with a successful response. These errors carry no error_description.

errorWhenWhat to do
access_deniedThe user denied access on the consent screen.Show a message and a button to try again.
login_requiredprompt=none, but the user isn’t signed in to Sentra, their session is older than max_age, or they must change their password first.Try again without prompt=none so the user can sign in.
consent_requiredprompt=none, but the user hasn’t consented to your app.Try again without prompt=none so the consent screen shows.
invalid_requestUnknown prompt value, max_age isn’t a whole number of 0 or more, code_challenge_method isn’t S256, or code_challenge isn’t 43–128 characters.Fix the /authorize parameters.
unsupported_response_typeresponse_type isn’t code.Send response_type=code.

Without prompt=none, Sentra returns no error in these situations: the user is asked to sign in, change their password or consent first.

POST /oauth/token

Token errors follow the OAuth 2.0 format, with a Cache-Control: no-store header:

curl -i -X POST "$SSO_API_URL/oauth/token" \
  -u "$SSO_APP_ID:$SSO_CLIENT_SECRET" \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode code=wrong-code \
  --data-urlencode redirect_uri="$SSO_REDIRECT_URI"
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Cache-Control: no-store

{"error":"invalid_grant","error_description":"code is invalid"}
Statuserrorerror_descriptionMeaning and action
400invalid_requestcode and redirect_uri are requiredcode or redirect_uri is missing.
400invalid_requestparameters must be sent in the body, not the URLMove the parameters from the query string to the body.
400invalid_requestuse one client authentication methodSend credentials with HTTP Basic or in the body, not both.
400invalid_requestclient_id does not match the Authorization headerThe client_id in the body differs from HTTP Basic.
400unsupported_grant_typeonly authorization_code is supportedSend grant_type=authorization_code.
401invalid_clientclient authentication failedWrong or missing App ID or Client secret, or the app is deactivated. After rotating the secret, update your .env.
400invalid_grantcode is invalidUnknown code, or it belongs to another app.
400invalid_grantcode was already usedThe code was already exchanged. Don’t repeat the exchange.
400invalid_grantcode expiredMore than 60 seconds passed. Exchange the code right away in the callback.
400invalid_grantredirect_uri does not matchSend the same redirect_uri as in /authorize.
400invalid_grantcode_verifier is required/authorize used PKCE; send the code_verifier.
400invalid_grantcode_verifier does not matchThe code_verifier doesn’t pair with the code_challenge. Check the value in the session.
400invalid_grantcode_verifier sent but no code_challenge wasSend code_verifier only when /authorize used PKCE.
400invalid_grantuser is not activeThe account is deactivated in Sentra. Refuse the sign-in.
429slow_downtoo many token requestsToo many requests from your IP. Wait a moment.
500server_errortry again laterA problem at Sentra. Try again later.
After any invalid_grant, the code can’t be used any more. Send the user to sign in again from the start; don’t retry with the same code.

GET /oauth/userinfo

curl -i "$SSO_API_URL/oauth/userinfo" -H "Authorization: Bearer x"
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

{"error":"invalid_token","error_description":"the access token is invalid or expired"}
Statuserrorerror_descriptionMeaning and action
401invalid_tokenmissing bearer tokenSend an Authorization: Bearer <token> header.
401invalid_tokenthe access token is invalid or expiredThe token is malformed or more than 15 minutes old. There’s no refresh token: ask the user to sign in again if you need fresh data.
401invalid_tokenthe application is not activeYour app is deactivated.
401invalid_tokenthe user is not activeThe account is deactivated in Sentra. End the user’s session in your app.
500server_errortry again laterA problem at Sentra. Try again later.