Authorization
Only use v3 of our auth-endpoints. Version 1 and 2 are deprecated and will be shut down by end of 2025!
For Userinterface
This Authorization-Flow (aka OpenId Connect Code grant Flow) serves to authorize an user between WebUntis and your 3rd-Party-Application including the neccessery Sessions/Cookies.
Call authorize Endpoint
GET:
{{API_URL}}/WebUntis/api/sso/v3/{{tenantId}}/authorize
?response_type=code
&scope=roster-core.readonly openid
&client_id={OIDC Client ID}
&redirect_uri={third_party_url}
&nonce=1234
Example:
1GET https://api.integration.webuntis.dev/WebUntis/api/sso/v3/1234/authorize?response_type=code&scope=roster-core.readonly%20openid&client_id=BestApp&redirect_uri=bestapp.example.domain.at/redirect?nonce=1234
Important:
- You need an active WU-session to get an id token!
- The redirect_uri must match the configured domain + sso-redirect-path in the platform-application-manager! Otherwise you get an “invalid_ressource” error.
- If you add the scope “untis-profile” you will get more information about the user in the JWT-token, but we cannot guarantee the backwards compatibility of this information. Changes might lead to developing-effort in your application. Better to use only the “sub” and call the OneRoster-User-Endpoint to get the information.
Get Access Token
POST:
{{API_URL}}/WebUntis/api/sso/v3/{{tenantId}}/token
?grant_type=authorization_code
&code={authorization_code from the first Endpoint}
&client_id={OIDC Client ID}
&client_secret={OIDC Secret}
Example:
1POST https://api.integration.webuntis.dev/WebUntis/api/sso/v3/1234/token?grant_type=authorization_code&code=HmToMB_iITpHLucs8RvrL8pEi6iizoKKK7_W8lJSi0k&redirect_uri=berry2b.example.domain.at/redirect&client_id=BestApp&client_secret=Rd5kweLWyww9TYPjjrrvCq3MnCnzezuUs
Info: For this Code-Flow you need to use the OIDC-Secret. (NOT the password)
Info: The response JWT-token includes the userinformation ("sub")!
Important: The header must include 'Content-Type: application/x-www-form-urlencoded'
For API-Integration
This Credentials-Flow (aka Client credentials grant OAuth2.0) serves to establish a Server2Server-Communication, so you can call our REST-APIs like OneRoster.
In our case, the OIDC Client ID is the username and we don’t use the OIDC secret as a password, we use a self-generated password. The password is generated when activating the platform-application.
Get Access Token
POST:
{{API_URL}}/WebUntis/api/sso/v3/{{tenantId}}/token
?grant_type=client_credentials
The header must include Basic Auth (based on username=OIDC Client ID and Password
generated by the Platform-Application-Manager).
The body must include grant_type=client_credentials. (Postman Body: x-www-form-urlencoded)
Example:
1https://api.integration.webuntis.dev/WebUntis/api/sso/v3/1600/token?grant_type=client_credentials
Info:
- For this Credential-Flow you need to use the Password. (NOT the OIDC-Secret)
- Get an access_token of type “Bearer” within the body response. With this token you can call the API-Endpoints.
- The token is valid for 3 minutes. But you can read this via "expires_in" in the response. It contains the number of seconds that the access token is valid. So please only request new tokens when it is really necessary. We highly recommend to use this. There are frameworks to use this out of the box.
GET /.well-known/openid-configuration
Returns the OpenID Connect configuration values from our Well-Known Configuration Endpoint, per the specification (OIDC-Spec).
You can get the right endpoints calling the well-known-endpoint via the API-URL:
Example:
https://api.webuntis.com/WebUntis/api/sso/v3/{tenantid}/.well-known/openid-configuration