API routes (Click a route to expand it, click here to expand/collapse all)
Auth API
GET/ap/{idToken} ⎘
Perform user authentication. Only supports the Authorization Code flow; the Implicit flow is not supported as it is deprecated
Parameter Location Type Requirements Optional Default value Description
idToken URI-Path string No Current established identification token during authorization process.
Response HTTP Type Description
Success 200 false Does not return a result since this is a navigation-endpoint. Instead, redirects to the redirect_uri specified on /oauth2/authorize upon completion, with URI-parameters as per OAuth2 specification.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
GET/ap/{idToken}/abort ⎘
If navigated to this URI, it means a user abort. This will trigger a redirect to the originally registered redirectURI encoded in the idToken.
Parameter Location Type Requirements Optional Default value Description
idToken URI-Path string No Current established identification token during authorization process.
Response HTTP Type Description
Success 200 false Does not return a result since this is a navigation-endpoint. Instead, redirects to the redirect_uri specified on /oauth2/authorize upon completion, with URI-parameters as per OAuth2 specification.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
GET/favicon.ico ⎘
Outputs the favicon for the AuthPortal.
Response HTTP Type Description
Success 200 false Outputs the favicon content directly
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
GET/oauth2/authorize ⎘
Perform user authentication. Only supports the Authorization Code flow; the Implicit flow is not supported as it is deprecated
Parameter Location Type Requirements Optional Default value Description
response_type URI-Query string No Response type per OAuth2.1 specification. Only the authorization code grant is supported (="code").
client_id URI-Query string No Client identifier per OAuth2.1 specification.
redirect_uri URI-Query string No Redirect URI to redirect to after authorization. Must be specified in our implementation.
code_challenge URI-Query string No Code challenge as generated per RFC7636, using S256-scheme.
scope URI-Query string Yes "" Requested access scope per OAuth2.1 specification. Optional; leave empty to let the authorization server decide/infer.
state URI-Query string Yes "" State as per OAuth2 specification, to be returned to redirect_uri.
Response HTTP Type Description
Success 200 None Does not return a result since this is a navigation-endpoint. Instead, redirects to the redirect_uri upon completion, with URI-parameters as per OAuth2 specification.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
GET/oauth2/publicKey ⎘
Returns the URL-base64-encoded JWT Public Key that can be used to verify the signature.
Response HTTP Type Description
Success 200 string URL-Base64-encoded public Verification Key for JWT verification. If Accept-header is NOT application/json, the publicKey is output in plain-text end the request is terminated.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
POST/ap/{idToken} ⎘
Back-end endpoint for the AuthPortal front-end only.
Parameter Location Type Requirements Optional Default value Description
idToken URI-Path string No Current established identification token during authorization process.
actionData POST-body string
format: json
 No
Submission data for current requested action state; differs per requested action. Empty object is considered a retry of the previous requested action.
| { email: string }
| { emailCode: string }
| { accessCode: string }
| { accessCode: string, markTrusted: boolean }
| { idDepartment: int }

The specific current action is always determined from the idToken state itself, to avoid bypassing required factors.
Response HTTP Type Description
Success 200 { idToken: string, action: "inputEmail" | "inputEmailVerificationCode" | "setAccessCode" | "inputAccessCodeAndRequestTrustedLocation" | "selectDepartment" | "redirect" | "abortError", actionDetails: | { uri: string }, | { message: string, length: int, numeric: boolean } | { message: string, length: int, numeric: boolean, confirmTrustedIP: string } | { departmentOptions: { id: int, name: string }[] } error?: string } Object with idToken (may be modified/updated), current requested action, optionally an error message and optionally action details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
POST/oauth2/token ⎘
Issues a KATEv2 access-token JWT and refresh-token.
Parameter Location Type Requirements Optional Default value Description
grant_type POST-body string
enum: [ "authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:token-exchange", "urn:ietf:params:oauth:grant-type:jwt-bearer" ]
 Yes "authorization_code" Grant type, following OAuth2.1 specification.
code POST-body string Yes "" Authorization code returned by /oauth2/authorize. Only required/applicable when grant_type = authorization_code.
code_verifier POST-body string Yes "" PKCE Code Verifier as per OAuth 2.1 PKCE specification (RFC7636). Only required/applicable when grant_type = authorization_code.
refresh_token POST-body string Yes "" Refresh token for access token renewal. Only required/applicable when grant_type = refresh_token.
redirect_uri POST-body string Yes "" Exactly the same redirect URI as used in /oauth2/authorize. Only required/applicable when grant_type = authorization_code.
client_id POST-body string Yes "" Exactly the same client ID as used in /oauth2/authorize. Only required/applicable when grant_type = authorization_code.
scope POST-body string Yes "" Requested access scope per OAuth2.1 specification. Cannot exceed the granted scope from the authorize-request. Optional; leave empty to let the authorization server decide/infer.
assertion POST-body string Yes "" Private Signed JWT, following RFC7523, section 2.1. Only required/applicable when grant_type = urn:ietf:params:oauth:grant-type:jwt-bearer. The JWT must be signed using an EdDSA private-key, and the public-key must be pre-registered with the auth-service corresponding the client_id.
Response HTTP Type Description
Success 200 { access_token: KATEv2accessTokenJWT, token_type: string, expires_in: int, refresh_token: KATEv2refreshToken, scope: string } OAuth2.1 Token response including refresh token.
{
access_token: KATEv2accessTokenJWT,
token_type: string,
expires_in: int,
refresh_token: KATEv2refreshToken,
scope: string
}
OAuth2Exception 400 OAuth2-compatible error. Response format differs from KATEv2 framework response format, see official OAuth2.1 specification for format. Possible error values:
  • invalid_request
  • invalid_client
  • invalid_grant
  • invalid_scope
  • unauthorized_client
  • unsupported_grant_type
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
Default APIs
GET/ ⎘
Provides the API-specification. Only enabled if API exposure is enabled.
Parameter Location Type Requirements Optional Default value Description
format URI-Query string
enum: [ "KateAPI", "InternalAPIMap", "OpenAPI", "Swagger" ]
 Yes "KateAPI" Documentation format. We support KateAPI documentation, Swagger/OpenAPI documentation and raw output of the internal API-map cache.
openApiVersion URI-Query int
enum: [ 2, 3 ]
 Yes 2 Version 3 is crappy with request bodies, so we prefer version 2 (which only sucks regarding Response definitions; hence we prefer KateAPI documentation).
Response HTTP Type Description
Success 200 object The API-documentation.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
Result wrappers (Click a result-wrapper to expand it)
Success
Error