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.
            lang POST-body string
            format: [A-Za-z0-9-]+
            Yes "en" Affected language; i.e. the one to be cleared, for example "en", "en-US" or "en-US-x-cw". If left empty, all languages for given namespace will be cleared. If provided, also requires namespace to be provided.
            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, for user grants, a refresh-token).
              Parameter Location Type Requirements Optional Default value Description
              grant_type POST-body string
              enum: [ "authorization_code", "refresh_token", "client_credentials", "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.
              client_secret POST-body string Yes "" Client secret (kate_cs_...) or API key (kate_ak_...) per RFC6749 section 2.3.1, as an alternative to HTTP Basic authentication. Never combine both methods. Omit for public clients.
              customer POST-body string Yes "" Target idCustomer. Only applicable when grant_type = client_credentials or urn:ietf:params:oauth:grant-type:token-exchange. Optional; required when the API key or client holds several grants without a default.
              department POST-body string Yes "" Target idDepartment. Only applicable when grant_type = client_credentials or urn:ietf:params:oauth:grant-type:token-exchange. Optional.
              subject_token POST-body string Yes "" KATE access token of the user to act on behalf of (RFC8693). Only required/applicable when grant_type = urn:ietf:params:oauth:grant-type:token-exchange.
              subject_token_type POST-body string Yes "" Type of subject_token (RFC8693): urn:ietf:params:oauth:token-type:access_token (default) or urn:ietf:params:oauth:token-type:jwt. Only applicable when grant_type = urn:ietf:params:oauth:grant-type:token-exchange.
              audience POST-body string Yes "" Audience (aud) of the issued token (RFC8693). Only applicable when grant_type = urn:ietf:params:oauth:grant-type:token-exchange. Optional.
              resource POST-body string Yes "" Resource indicator (RFC8707), used as the audience (aud) of the issued token. Applicable when grant_type = client_credentials or urn:ietf:params:oauth:grant-type:token-exchange (when audience is empty). Optional.
              Response HTTP Type Description
              Success 200 { access_token: KATEv2accessTokenJWT, token_type: string, expires_in: int, refresh_token?: KATEv2refreshToken, issued_token_type?: string, scope: string } OAuth2.1 Token response.
              {
              access_token: KATEv2accessTokenJWT,
              token_type: string,
              expires_in: int,
              refresh_token?: KATEv2refreshToken, // Only for user grants (authorization_code, refresh_token); never for client_credentials, token exchange or jwt-bearer.
              issued_token_type?: string, // Only for token exchange (RFC 8693): urn:ietf:params:oauth:token-type:jwt.
              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
              • invalid_target
              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
              • Authentication scheme: ClientCredentialsAuth Requires: None ⎘
              Auth Management API
              POST/mgmt/oauth2/clients/synchronizeConfig ⎘Authentication required
              Imports the configured kate.oauth2.clients / kate.oauth2.confidentialClients into the database. Idempotent on client_id; never overwrites existing clients.
              Response HTTP Type Description
              Success 200 { created: string[], skipped: string[], errors: object } client_ids created/skipped, and errors per client_id
              MySQLException 500 MySQL related exception. See details for specific exception 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:
              Yes
              • Authentication scheme: JWTAuth Requires: ('kate:admin' OR 'kate:migration') ⎘
              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
                Authentication schemes (Click an authentication scheme to expand it)
                ClientCredentialsAuth
                JWTAuth
                Result wrappers (Click a result-wrapper to expand it)
                Success
                Error