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
POST/mgmt/plugin/clear/translations ⎘Authentication required
Clears the Translations-plugin cache. Should only be invoked against services that utilize this plugin.
Parameter Location Type Requirements Optional Default value Description
rfc5646languageTag POST-body string
format: [A-Za-z0-9-]+
 Yes null Language to clear the translations for, for example "en", "en-US" or "en-US-x-cw". If not provided, clears the translations for all languages
rootNamespace POST-body string
enum: [ "ui", "mail", "err", "red", "wf", "mgmt" ]
 Yes null Root Namespace to clear specific cached translations, for example "ui" "red". If not provided, clears the root namespace for all translations.
Response HTTP Type Description
Success 200 bool Returns true.
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:
Yes
Authentication scheme:
JWTAuth
Required flags:
kate:admin ⎘
Authentication schemes (Click an authentication scheme to expand it)
JWTAuth
Result wrappers (Click a result-wrapper to expand it)
Success
Error