Loading... Loading ...
expand / collapse all

Airlock IAM Transaction Approval REST API

About this documentation

The focus of this documentation is on the REST API endpoints and their technical usage. It does not provide information about its usage in terms of examples.
Please consult the Airlock IAM documentation for further information. It provides conceptual and technical information as well as example REST call sequences.

Important

The use-cases in the Transaction Approval REST API are designed for trusted users only and should never be available to end-users.

Transaction Approval allows to re-check the second factor of a user for situations where additional security about the identity of the user is desired.

General information (for all IAM REST APIs)

Introduction to the Airlock IAM REST API

The Airlock IAM REST API is a technical interface offering a set of services in a RESTful way. Starting with IAM 6.1 with internal admin use cases such as user management, it has continuously been extended to cover Loginapp use cases as well. More services will follow in future releases.

The main purpose of the REST API is the machine-to-machine communication where web UIs are not applicable. Usage scenarios include:

  • user management by third-party back-end applications (admin)
  • password- and token management (admin)
  • authentication (login)
  • user self-registration (login)

Clients of the IAM REST API could be mobile applications, single-page-applications or technical back-ends.

Scope

The Airlock IAM REST API consists of three parts. The "Adminapp REST API" that offers an alternative interface for the Adminapp, the "Loginapp REST API" that offers end-user use cases such as authentication and user self-services and the "Transaction Approval REST API" that allows an authenticated user to verify transactions with the user's 2nd authentication factor.

Implementation and Integration

JSON:API format

Where applicable, the IAM REST API follows the JSON:API Specification. In a nutshell, it specifies a schema for the request and response JSON objects. Most important points are:
  • a top-level JSON:API document contains at least one resource object, a collection of resource objects or a certain amount of error objects. Optionally, it contains also:
    • links
    • a meta data object
    • embedded, referenced resource objects. This prevents the need for extra requests to these resources.
  • every resource object has a symbolic type and an id. Optionally, it contains also:
    • an attribute object
    • a relationship object with references to other resources
    • links (e.g. self-links or links to sub resources)
JSON:API has been developed with focus on CRUD operations. Since the IAM REST API was not designed as a CRUD interface, it does not follow the JSON:API format in every call. JSON:API usually suggests PATCH to update existing resources. This is suitable if the updated elements are seen as data attributes of an object. To ensure that operations only cause consistent and meaningful changes, the IAM API does in general not allow direct changes on the resource attributes. Instead, there are calls reflecting operations or use cases on resources. Examples:
POST https://www.airlock.com/auth-admin/rest/users/{userId}/lock/
POST https://www.airlock.com/auth-login/rest/public/users/register/
POST https://www.airlock.com/auth-login/rest/public/users/{userId}/registration/verify/
These operations consist of a POST request to the respective URI. Since such operations are not covered by the JSON:API Specification, custom request formats have been defined. Where suitable, the JSON:API format is still being employed in the responses in order to benefit from structural elements such as links and metadata.

URIs

When building a client application to the Airlock IAM REST API, please make sure that the URLs are not hard-coded in the client, but configurable in the following parts:
https://someHost:8080/
contextPath
/users/user123/secret-questions/answers/missing
  • Domain and port
    : domain name and optional port should be configurable in the client
  • Context path
    : This prefix depends on the name of the IAM instance. If run behind Airlock WAF, it's determined by a mapping name. Allow this part to consist of multiple path segments such as auth-login/rest.
  • Resource path
    : This part of the URI is independent of deployment and considered stable.

Date and time format

Timestamps and date-only values in the IAM REST API are in ISO 8601 format which is defined as
date-fullyear   = 4DIGIT
date-month      = 2DIGIT  ; 01-12
date-mday       = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on
                             ; month/year
time-hour       = 2DIGIT  ; 00-23
time-minute     = 2DIGIT  ; 00-59
time-second     = 2DIGIT  ; 00-58, 00-59, 00-60 based on leap second
                             ; rules
time-secfrac    = "." 1*DIGIT
time-numoffset  = ("+" / "-") time-hour ":" time-minute
time-offset     = "Z" / time-numoffset

partial-time    = time-hour ":" time-minute ":" time-second
                     [time-secfrac]
full-date       = date-fullyear "-" date-month "-" date-mday
full-time       = partial-time time-offset

date-time       = full-date "T" full-time
The format date-time is used for timestamps (values containing the date and the time of the day). Examples of such values are
2011-12-03T10:15:30.000+01:00
2018-02-06T15:58:53.661Z
Timestamps always contain time zone information by means of a UTC offset. If the server runs in the UTC time zone, the UTC offset of 0 is represented as Z. Java developers may use the following pattern for parsing and/or formatting ISO 8601 timestamps
yyyy-MM-dd'T'HH:mm:ss.SSSXXX

The IAM REST API accepts timestamps in several formats, but they must always contain a time and timezone component. It is recommended to format timestamps as described above to avoid ambiguities.

The format full-date is used for values that contain a date without the time of day. An example of such a value is
2011-12-03
The corresponding pattern to be used in Java is
yyyy-MM-dd

API changes and versioning

While great care is taken to keep this API stable, changes in upcoming releases are unavoidable. Most of the changes however should not break existing clients - they will merely add additional information into responses or offer entirely new operations or even resource types. For breaking changes, the IAM REST API introduces the concept of iam-variants. It is a media type parameter that can be added to the request's Accept header if a client wishes to receive a certain new version or "variant". The response's Content-Type lists the variant that is actually returned:
GET /api/user/foo
Accept: application/vnd.api+json; iam-variants="extension-a,extension-b,extension-c"

200 OK
Content-Type: application/vnd.api+json; iam-variants=extension-b
A client that does not specify any variants will receive data in the format of version 6.1 which is considered the baseline. Supported iam-variants will be documented in the documentation of the specific call once available.

Incubating features

New features which are still under active development are marked with an
 INCUBATING
tag. Since changes to these features are possible in the future, it is not advisable to implement clients using them.

Charset and Encoding

The REST API uses UTF-8 for character encoding. Clients sending an Accept-Charset header which does neither contain UTF-8 nor a wildcard * will receive a 406 Not Acceptable response from the server. It is recommended to not send an Accept-Charset header or explicitly request UTF-8.

Locale

Clients may set the Accept-Language header as specified by RFC 2616. If set, IAM will determine the best matching language based on the configured language settings. If the header is a) not set, b) malformed or c) does not match any configured language, the configured default language is used. The language is relevant if messages like SMS or email are sent to a user upon a REST call.

CSRF protection

IAM REST calls are CSRF protected (see here for further information). Every* endpoint requires the custom header X-Same-Domain with a non-empty value (e.g. X-Same-Domain: 1). A request without this header will be rejected with HTTP status code 400 and error code CSRF_HEADER_MISSING.

We briefly explain how this mechanism protects against CSRF attacks.

Cross-Site requests can either be 'simple' or 'non-simple', as explained in CORS. Simple requests are sent to the server (IAM) in any case and can thus be employed to execute CSRF attacks. In case of 'non-simple' requests, browsers first send a preflight request to the server. The actual request is only executed if the server explicitly allows it by white-listing the request's origin. Forcing cross-site requests to be 'non-simple' therefore protects against CSRF attacks, as only white-listed cross-site requests are executed.

IAM forces all requests to have the custom header X-Same-Domain which makes them 'non-simple'. This establishes the CSRF protection as explained above. Allowed origins to be accepted can be white-listed in IAM's CORS settings. By default, this white-list is empty and all cross-origin requests are denied.

For backward compatibility with older clients, this check can be disabled in the Loginapp- and Adminapp REST configuration. The operation with disabled CSRF protection is strongly discouraged.

* Endpoints that are designed in accordance with an external specification (such as a RFC) are excluded from requiring the X-Same-Domain header. Refer to the documentation of endpoint operations below to see where this applies and how CSRF protection is ensured instead.

Response format

Responses in the Airlock IAM REST API follow the JSON:API specification as defined in http://jsonapi.org/. JSON:API distinguishes between regular and error responses, where errors have a HTTP status code in the range 4XX or 5XX. A detailed description of a call's particular regular response is given in its endpoint description. Error responses are generic and decribed below.
Error Responses
Error responses are sent to the client if either the user provides wrong input, or if server-side errors occur. They have HTTP status codes in the range 4XX (client errors) or 5XX (server errors).
Example
{
  "meta": {
    "type": "jsonapi.metadata.document",
    "timestamp": "2016-04-25T13:57:26.122+00:00"
  },
  "errors": [
    {
      "id": "6117:5385",
      "status": 400,
      "code": "INVALID_REQUEST_FORMAT"
    }
  ]
}
An error response consists of a meta element and an array of errors. The array contains one or more error objects, each with optional id, status and code that indicates what kind of error has occured. A detailed description of the error format can be found here http://jsonapi.org/format/#errors.
404 (NOT FOUND) response
A call will be answered with a 404 - NOT FOUND response if the requested resource cannot be found. This might be the case if
  • the requested URL contains a typo
  • the requested URL contains an identifier but no entity with this identifier exists in the context of the current request.
    In cases where the entity that could not be found is a user, the error code USER_NOT_FOUND is set in the response.
415 (UNSUPPORTED MEDIA TYPE) response
The HTTP status code 415 - UNSUPPORTED MEDIA TYPE indicates that the server refuses to accept the request because the payload format is in an unsupported format. The format problem might be due to the request's indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly.

Every endpoint declares the accepted Content-Type which is typically application/vnd.api+json and/or application/json.

503 (SERVICE UNAVAILABLE) response
The server may respond with HTTP status code 503 - SERVICE UNAVAILABLE if the server is currently unavailable. This may happen if the server is down for maintenance. In the Loginapp REST API, this happens if a maintenance message indicates that the system is unavailable at the time of request. Generally, this is a temporary state.
Errors on updating relationships
Deviating from JSON:API specification, failed attempts to update relationships are always answered with status code 400 - BAD REQUEST.
Error responses in flows

In flows, the HTTP status code 400 - BAD REQUEST indicates that the previous request has been rejected and the client should try to resume the flow with the step indicated.

The HTTP status code 403 - FORBIDDEN means that the flow has been aborted by the engine and the client should not attempt to make any further calls for this flow, as they will not succeed. For instance, this may happen if the call is unexpected or if a user is locked. Such situations may require an intervention of the helpdesk for the user to continue with the process.

Error Codes

Error objects can contain an optional code that gives more detail about the error situation. Currently, the following generic error codes can occur:

  • AUTHENTICATION_FAILED: the authentication failed for some unspecified reason.
  • AUTH_METHOD_INACTIVE: the authentication failed since the current authentication method is inactive / disabled.
  • CAPTCHA_CHECK_FAILED: the requested resource is protected by CAPTCHA but an invalid or no CAPTCHA was provided.
  • CLIENT_CERTIFICATE_MISSING: a client certificate is required when calling the requested resource.
  • CONCURRENT_ACCESS: concurrent calls within a user session have been detected (typically returned from an authentication flow).
  • CSRF_HEADER_MISSING: the call is CSRF protected and requires the header X-Same-Domain. See CSRF Protection.
  • FLOW_START_NOT_ALLOWED: the flow is not allowed because the user session already contains data, e.g. a user may be logged in. The user must log out first in order to start this flow.
  • FLOW_SESSION_EXPIRED: the flow is no longer valid because some initial tags (which might have been used in preconditions or skip conditions during the execution of this flow) have expired.
  • GOTO_FAILED: the requested goto is not possible. The target step is not allowed from the current step or it does not exist in the flow at all.
  • INVALID_REQUEST_FORMAT: the request format is syntactically invalid (parse error).
  • NO_VALID_TOKEN: no valid token could be found. E.g. two factor authentication with mTAN in progress, but no mTAN number registered.
  • UNEXPECTED_CALL: the call to the requested resource is unexpected. Happens for instance in flows if the attempted call does not match the step that is expected next. In such cases, the current flow is generally aborted, but the user session remains intact. The user may subsequently restart the flow. Calls to endpoints that select and start flows (e.g. application access) are an exception to this, as they do not terminate an ongoing flow if called unexpectedly.
  • USER_INVALID: the user is invalid.
  • USER_LOCKED: the user is locked.
  • USER_NOT_FOUND: the specified user could not be found.
  • USER_NOT_UNIQUE: the specified user could not be uniquely identified.
  • USER_ROLE_MISSING: the user does not have sufficient roles to perform an action (typically returned from an authentication flow).
  • USER_TEMPORARILY_LOCKED: the requested operation cannot be performed because the user is temporarily locked. Note that this code is not returned by the operation which caused the temporary lock itself.
  • VALIDATION_FAILED: the supplied attributes could not be validated successfully. See validation failures for detail codes.
  • TECH_CLIENT_NOT_FOUND: the specified technical client could not be found.

The listing below shows which generic errors can occur for the different application parts. Additional endpoint-specific error codes are documented in the individual endpoint documentation. Generic errors are not documented on individual endpoints. Callers must expect them as documented below.

All endpoints Flow-based APIs (Loginapp) Loginapp Adminapp
CSRF_HEADER_MISSING (400)
CLIENT_CERTIFICATE_MISSING (403)
INVALID_REQUEST_FORMAT (400)
USER_INVALID (403)
USER_LOCKED (403)
USER_TEMPORARILY_LOCKED (403)
VALIDATION_FAILED (400 / 409)
USER_NOT_FOUND (400 / 403)
CONCURRENT_ACCESS (400)
FLOW_START_NOT_ALLOWED (403)
FLOW_SESSION_EXPIRED (403)
GOTO_FAILED (400)
NO_VALID_TOKEN (403)
AUTH_METHOD_INACTIVE (403)
UNEXPECTED_CALL (400 / 403)
CAPTCHA_CHECK_FAILED (400)
USER_ROLE_MISSING (403)
USER_NOT_UNIQUE (409)
TECH_CLIENT_NOT_FOUND (404)
Validation Failures
Some REST endpoints accept multiple, potentially configurable attributes that must be validated by IAM. For a better user experience, IAM validates these attributes as a batch and - in case of validation failures - responds with a cumulative error response that contains details about the validation issues found on a per-attribute basis.

Such validation responses typically have a HTTP status code 400 (Bad Request) or 409 (Conflict) and contain one or more error elements with error code VALIDATION_FAILED. Note that password policy violations are reported with the same error structure but with error code PASSWORD_POLICY_VIOLATED as described below.

The IAM request validation is primarily designed to report semantic errors, such as wrong user input, in contrast to syntax errors. In a setup where API requests are routed through Airlock WAF with upstream OpenAPI validation, syntactically invalid requests are blocked before they reach IAM. Examples of syntax errors are:

  • The request does not contain valid JSON.
  • The request lacks a mandatory JSON property (as defined in this document).
  • The request contains a JSON property value of the wrong JSON type (e.g. number instead of string)
Therefore, REST API clients should not rely on IAM to provide validation failure responses detailing syntax errors.

Like other error responses, validation failures conform to the JSON:API specification and can contain the following error properties:

  • code: VALIDATION_FAILED
  • source.pointer (optional): the path to the attribute in the request that caused the validation failure
  • source.parameter (optional): the parameter in the request that caused the validation failure
  • meta.detail (optional): a detail code identifying the validation failure
  • meta.parameters (optional): a map of parameters that further describe the validation failure
Example
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2017-12-12T09:29:01.259+01:00"
    },
    "errors": [
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/newPhoneNumber"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "MAX_LENGTH",
                "parameters": {
                    "actualLength": 26,
                    "maxLength": 12
                }
            }
        },
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/label"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "REQUIRED"
            }
        }
    ]
}
The example shows the response of a failed validation. It contains two VALIDATION_FAILED errors concerning the two attributes newPhoneNumber and label. The first error has a detail code value MAX_LENGTH which is further specified by parameters actualLength and maxLength. It tells the caller that the phone number sent with the request had length 26 but only 12 characters are allowed.

The second error informs the caller about a missing field in the request. The attribute label is required and must be included in the request.

Validation failure detail codes

Currently, the following detail codes for validation failures can occur:

Generic Detail Codes

Detail Code Parameters Comment
REQUIRED - The attribute is mandatory.
NOT_NULL - The attribute is optional but is not allowed to be set to null.
WRONG_FORMAT - The supplied format is wrong.
NOT_UNIQUE - The supplied value is not unique.
BEFORE before (date-time string) The supplied date value must be before the date specified by the 'before' parameter.
AFTER after (date-time string) The supplied date value must be after the date specified by the 'after' parameter.
NOT_ADDABLE - The supplied value cannot be added.
NOT_REMOVABLE - The supplied value cannot be removed.
UNEXPECTED - The supplied attribute is unexpected and must not be sent by the client.
MIN_LENGTH minLength (integer), actualLength (integer) The supplied value must have a minimum length as specified by the 'minLength' parameter.
MAX_LENGTH maxLength (integer), actualLength (integer) The supplied value must have a maximum length as specified by the 'maxLength' parameter.
INVALID_VALUE - The supplied value is invalid.
OUTSIDE_RANGE - The supplied value is outside of an allowed range.
READ_ONLY - The supplied attribute is read-only and cannot be changed.
NOT_FOUND - An object / resource associated with the supplied value could not be found.
MIN min (integer) The supplied value must have a minimum value as specified by the 'min' parameter.
MAX max (integer) The supplied value must have a maximum value as specified by the 'max' parameter.
SIZE min (integer), max (integer) The supplied value's length boundaries must be between 'min' and 'max'.
INVALID_ELEMENT_NAME name (string) The attribute contains an element with an invalid name.

A robust client should be prepared to handle all of the above detail codes in any call that declares to return a VALIDATION_FAILED error.

Password Policy Violation Detail Codes

For backward compatibility, password policy violations are not reported under the error code VALIDATION_FAILED but PASSWORD_POLICY_VIOLATED instead. The structure of the errors remains as described above.
Detail Code Parameters Comment
UNSPECIFIED - The password policy validation failed due to an unknown reason.
ON_BLACKLIST - The password policy validation failed because the chosen password is on a black list.
CONTAINS_FORBIDDEN_CHARS forbiddenChars (string) The password policy validation failed the chosen password contains forbidden characters.
REQUIRES_CHARS requiredChars (string list) The password policy validation failed because the chosen password lacks required characters. The list contains patterns describing required characters.
SAME_AS_OLD - The password policy validation failed because the chosen password is the same as the old password.
TOO_LONG actualLength (integer), maxLength (integer) The password policy validation failed because the chosen password is too long.
TOO_SHORT actualLength (integer), minLength (integer) The password policy validation failed because the chosen password is too short.
TOO_SILLY - The password policy validation failed because the chosen password is too silly.
TOO_YOUNG - The password policy validation failed because the chosen password must not be changed again.
VALID_FLAG_VIOLATION - The password policy validation failed because of the user's password valid flag.
EXPIRED - The password policy validation failed because the password is expired.
IN_HISTORY - The password policy validation failed because the password is the same as a previously used password.

Above detail codes can result only from endpoints that validate a (new) password.

Request Query Parameters

Paging
Query parameters
page[limit]
page[offset]
Limit/Size
The maximum number of elements to include in the response (the server will constrain the passed limit to its internal maximum of 500). Choosing the right page size can improve performance of the client.
Offset
Offset of the first element to retrieve. Used in combination with a limited page size to retrieve a specified number of entries from the server.
Example (without URL encoding):
Query: ?page[limit]=20&page[offset]=40
Assuming the total number of results is 60, this query will return the last 20 entries of the total result set. Make sure to URL-encode parameter names and values before sending them.
Filtering
Query parameter
filter
Syntax
A single filter has the structure: name operator expression
  • name - The name of the dimension to filter on
  • operator - defines the type of filter match to use
  • expression - states the values included in the results
Note: filtering depends on the capabilities of the configured data source.
Operators:

== (exact match)
=@ (contains substring)

Combining filters:

OR logic - defined using commas (,) inside a filter expression
AND logic - achieved by providing multiple filter parameters for a request

Note: Each filter is evaluated individually before all filters are combined into an AND logical expression.
Example (without URL encoding):
Query: ?filter=username==john,surname==doe&filter=streetnumber=@2
Result will return all users with either username 'john' or surname 'doe' which live on any street with a number two in it. Make sure to URL-encode parameter names and values before sending them.
Sorting
Query parameter
sort
Syntax
Sort criteria are defined by a single string containing an arbitrary number of sort fields. Each sort field is in turn defined by a field name and a direction (ascending or descending).
SortCriteria = [ Criterion { ',' Criterion} ]
Criterion = [ '-' ] identifier
  • Identifier - The field to sort on, e.g. user context data
  • Criterion - An expression stating the field to sort on and the direction (ascending or descending). Sorting descending is done by declaring a '-' before the identifier. The default is to sort ascending.
  • SortCriteria - One or multiple criteria separated by a comma ','. Sort criteria are applied in the order they are declared. The next sort criterion in a list of criteria is only applied if two entries are equal by the former sort criterion.
Note: sorting depends on the capabilities of the configured data source.
Example (without URL encoding):
Query: ?sort=name,-email
Results will be sorted first by name and second by email (in reverse order). The second sort criteria is only applied if two results have an equal name. Make sure to URL-encode parameter names and values before sending them.

Configuration Contexts

The IAM REST interface supports Configuration Contexts which are determined by a Context Extractor. For every request, a configuration context is determined and the associated configuration applies for the scope of this request. As a result, contexts might change from request to request.

For multi-step use cases (such as email- or mTAN self-services) or flows, this behavior is undesired. Any configuration change during a multi-step use case could lead to unexpected behavior. IAM therefore checks that configuration contexts remain constant during multi-step use cases. If a context change is detected, the associated use case is terminated. Context extractors must be designed / configured in a way that no configuration contexts changes occur during multi-step use cases.

Flow control and flow status

Flows are a fundamental concept that is used in various parts of Airlock IAM. A high-level description of the flow concept can be found in the Airlock IAM documentation. This section focuses primarily on the technical aspects of the REST interface.

Fundamentals

  • A flow is a sequence of configurable steps that is executed in a strictly defined order, controlled by a state machine. Each step has a task, e.g. authentication with a specific factor.
  • Steps can be interactive or non-interactive. While interactive steps require input from a REST call, non-interactive steps run directly after the previous step without receiving input via the REST interface.
  • A non-interactive flow consists of a series of non-interactive steps. This means that the flow runs completely without interaction after the start.
  • Steps can either be successful, which leads to the next step in the flow becoming active, or they can result in an error state. Depending on the severity of the error, this means that the last activity on the step can be retried or that the entire flow is aborted.
  • Flows end successfully when the last step has been completed successfully.
  • IAM models specific flows for the various application parts. The different flows are known as flow types. Examples of flow types are authentication, public self-service, protected self-service, user self-registration among others.
  • Only one flow can be running per session at the same time. A running flow must be explicitly terminated before a new flow can be started.
  • Starting flows

    Flows have to be selected and started explicitly. Only if there is a default flow defined in the configuration, a direct call to the REST API of the first step also initiates a flow start. See the detailed endpoint documentation for such flow start endpoints.

    Ending flows

    Flows end automatically once the last step completed successfully or when they run into an error without retry option. However, they can also be terminated at any time by calling the flow termination endpoint specific to each flow type. These endpoints have the form DELETE /.../flow/. Aborted flows always return an error status code.

    Interpretation of responses from flow endpoints

    There are two types of REST endpoints in flows: those that can continue the flow and those that remain in the current step and only return data to the client.

    Flow-driving endpoints

    Endpoints that continue the flow have a "type" attribute of the format flow-type.session. In the "attributes" section, their responses can contain an attribute called "nextAuthStep" (in authentication flows) or "nextStep" (in all other flow types).

    Example

    {
      ...
      "data": {
        "type": "authentication.session",
        "id": "1234",
        "attributes": {
          "nextAuthStep": "MTAN_OTP_REQUIRED",
          "resendPossible": true,
          "phoneNumber": "+41791234567"
        }
      }
    }
    The attribute value of "nextStep" (or "nextAuthStep") instructs the client what to do next.
    Response status codes
    In addition to the general properties described in Response Format, responses from flow endpoints are to be interpreted as follows:
    Response properties Description
    200 OK (response containing "nextStep" or "nextAuthStep") The last input was successfully processed by the flow. The flow is still running.
    200 OK (response not containing "nextStep" or "nextAuthStep") The flow has ended successfully.
    400 Bad Request The last input could not be successfully processed by the flow. The flow is still running, a retry is possible in the current step.
    403 Forbidden The last input could not be successfully processed by the flow. No (further) retry possible, the flow was aborted.
    Further properties (e.g. error codes) are specified in more detail in the documentation for the individual endpoints.

    Data retrieval endpoints

    Endpoints that only deliver data but cannot continue the flow can be recognized by a "type" attribute that has no .session suffix. These endpoints often end with retrieve in the URL.

    Example

    {
      ...
      "data": {
        "type": "authentication.mtan.token",
        "id": "1234",
        "attributes": {
          "number": "+41791234567",
          "label": "My phone",
          "defaultNumber": true
        }
      }
    }

    Transaction Approval API

    Transaction approval relies on the same flow model as the Authentication API. Please refer to that documentation for an in-depth explanation.

    Next Approval Step Codes

    For each nextStep code, one or more follow-up calls are possible. These are as follows:

    nextStep Code Possible next call(s)
    AIRLOCK_2FA_DEVICE_CHOICE_REQUIRED POST /transaction-approval/airlock-2fa/devices/retrieve/
    POST /transaction-approval/airlock-2fa/devices/{id}/select/
    AIRLOCK_2FA_POLLING_REQUIRED POST /transaction-approval/airlock-2fa/status/poll/
    AIRLOCK_2FA_POLLING_OR_OTP_REQUIRED POST /transaction-approval/airlock-2fa/status/poll/
    POST /transaction-approval/airlock-2fa/offline/
    AIRLOCK_2FA_OTP_REQUIRED POST /transaction-approval/airlock-2fa/challenge/retrieve/
    POST /transaction-approval/airlock-2fa/otp/check/
    AIRLOCK_2FA_MOBILE_ONLY_CHALLENGE_RETRIEVAL_REQUIRED POST /transaction-approval/airlock-2fa/mobile-only/challenge/retrieve/
    CRONTO_DEVICE_CHOICE_REQUIRED POST /transaction-approval/cronto/push-devices/retrieve/
    POST /transaction-approval/cronto/push-devices/{id}/select/
    POST /transaction-approval/cronto/offline/
    CRONTO_OTP_REQUIRED POST /transaction-approval/cronto/challenge/retrieve/
    POST /transaction-approval/cronto/otp/check/
    POST /transaction-approval/cronto/otp/poll/ (if online validation active)
    MTAN_OTP_REQUIRED POST /transaction-approval/mtan/otp/check/
    POST /transaction-approval/mtan/otp/resend-info/retrieve/
    POST /transaction-approval/mtan/otp/resend/
    MTAN_TOKEN_CHOICE_REQUIRED POST /transaction-approval/mtan/tokens/retrieve/
    POST /transaction-approval/mtan/tokens/{id}/select/
    MATRIX_RESPONSE_REQUIRED POST /transaction-approval/matrix/challenge/retrieve/
    POST /transaction-approval/matrix/check/
    MESSAGE_ACKNOWLEDGMENT_REQUIRED POST /transaction-approval/message/acknowledge/
    NEXT_OTP_REQUIRED POST /transaction-approval/otp/check/
    OTP_REQUIRED POST /transaction-approval/otp/check/
    PARAMETERS_REQUIRED POST /transaction-approval/parameters/
    SELECTION_REQUIRED POST /transaction-approval/selection/options/retrieve/
    POST /transaction-approval/selection/options/{id}/select/
    USERNAME_REQUIRED POST /transaction-approval/user/identify/

    Additional attributes in transaction approval flow responses

    Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type transaction-approval.session and to the meta data of error responses. The possible attributes often depend on the nextStep code:

    nextStep Code Additional Attribute Type Description/Comment
    nextAuthStep: AIRLOCK_2FA_POLLING_REQUIRED
    AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED
    challengeImage string Base64-encoded QR code for Online QR Code authentication.
    nextAuthStep: AIRLOCK_2FA_POLLING_REQUIRED
    AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED
    appApprovalUrl string App URI to open the Online QR Code challenge in a mobile app.
    nextAuthStep: CRONTO_OTP_REQUIRED challenge object The Cronto Challenge
    • challengeImage (string): Base64-encoded challenge image (cryptogram) in "image/png" format.
    • secureChannelChallenge (string): The secure channel challenge to use in app-to-app scenarios.
    • onlineValidation (boolean): Indicates whether "online validation" is available. If true, the Cronto app can send the OTP directly to the server.
    • pushed (boolean): Indicates whether the challenge has been pushed directly to the device / Cronto app.
    • pushDevices (list of objects): Describes the devices to which the challenge has been pushed. Only available if the challange was pushed, each containing the following fields:
      • id (string): Unique identifier of the device.
      • label (string): Optional label of the push device.
      • platform (string): The device platform. One of 'IOS' or 'ANDROID'
    MESSAGE_ACKNOWLEDGMENT_REQUIRED messageId string Indicates which pre-configured message ID needs to be handled and acknowledged by a client (using POST /transaction-approval/message/acknowledge/). One of the attributes messageId and serverMessage is guaranteed to be present.
    MESSAGE_ACKNOWLEDGMENT_REQUIRED serverMessage string The server-generated message that needs to be acknowledged by a client (using POST /transaction-approval/message/acknowledge/). One of the attributes messageId and serverMessage is guaranteed to be present.
    MTAN_OTP_REQUIRED phoneNumber string The phone number the mTAN OTP was sent to. Depending on the configuration, this value is masked.
    MTAN_OTP_REQUIRED resendPossible boolean Indicates whether resending the SMS can be requested (using POST /transaction-approval/mtan/otp/resend/)

    Transaction Approval REST call documentation

    • Deprecated.

      Deprecated:

      {{baseUrl.value || ' '}}
         {{role}}{{$last ? '' : ', '}}

      Body

      Accept:
      no type

      Returns

      Content-Type:
      no type

      Response Headers

      Status codes



    • Interfaces not documented

      MireDot believes that the Java methods below correspond to REST interfaces, but somehow had problems parsing/processing these interfaces and therefore excluded them from the generated documentation. We would very much appreciate it if you would send us the interfaces (not the implementations) and the types used (returntype, parameters). This will allow us to further improve MireDot and better document your interfaces in the future.

    Below is a list of potential problems detected by MireDot. They can be severe or not. Some of them wil result in low quality documentation, some are real implementation issues. With each warning, the Java method causing the problem is documented.

      • method:

      not shown here because this documentation was generated by the free version of MireDot. As such, not all features are supported.