Troubleshooting
A reference for diagnosing and resolving common integration issues. Each entry describes what you observe, why it happens, and how to fix it.
invalid_grant error when obtaining an access token
Section titled “invalid_grant error when obtaining an access token”The token endpoint returns invalid_grant when using the Client Credentials flow.
Cause
The OIDC client secret and the platform-generated password are not interchangeable. Each credential belongs to a specific flow:
| Flow | Credential to use |
|---|---|
| Client Credentials (server-to-server) | Platform-generated password sent via the credentials webhook |
| Authorization Code (SSO / user login) | OIDC client secret from PAM |
Resolution
For the Client Credentials flow, use the password delivered to your endpoint via the Credentials Webhook, not the OIDC client secret.
User is not redirected back to the application after IServ login
Section titled “User is not redirected back to the application after IServ login”After completing IServ authentication, users land back on WebUntis rather than being returned to the partner application. Restarting the SSO flow after authentication succeeds as expected.
Cause
This occurs when a user does not already have an active browser session in WebUntis before the SSO flow begins. The intermediate redirect to an external identity provider (such as IServ) can cause the original redirect state to be lost.
Status
This is a known issue currently tracked in the Untis backlog. There is no workaround available at this time.
Login URL does not start a new authentication flow
Section titled “Login URL does not start a new authentication flow”A user opens the application from the Untis Platform dashboard but is authenticated as a different user from a previous browser session.
Cause
If a partner application skips the authentication flow when a session already exists, and does not verify that the inbound user matches the active session, a different user account may be active than the one who launched the app.
Resolution
Treat every incoming request to your Login URL as the start of a new authentication flow. If your application already has an active session, terminate it and re-initiate the OIDC Authorization Code flow before establishing the new session. This ensures that the user authenticated in your application always matches the user who launched it from the Untis Platform.
OneRoster returns no students, but students exist in masterdata
Section titled “OneRoster returns no students, but students exist in masterdata”Querying the OneRoster API returns no students (or an empty result), even though the school has students in WebUntis.
Cause
The OneRoster API is user-account-centric. It only returns persons who have an active user account in the system. Students who exist in the masterdata but have no user account are not exposed through OneRoster.
Resolution
If you need to access students who do not have user accounts, use the Student Management API, which operates on masterdata rather than user accounts.
students/{id} returns no result
Section titled “students/{id} returns no result”Calling students/{id} returns no result for an ID that is known to exist.
Cause
The {id} path parameter resolves against the externalKey field — the identifier used by upstream school management software — not the internal Untis record ID. The externalKey is not always populated; it is set when data originates from an external source but may be absent for records created directly in WebUntis.
Resolution
To retrieve a student by their internal Untis ID, use the filter query parameter instead:
GET /WebUntis/api/rest/extern/v3/students?filter=id='1'This targets the internal id field directly and works regardless of whether an externalKey is set.