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

Airlock IAM Loginapp 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.

The intended users of the Loginapp REST API are end-users of Airlock IAM. Typical use-cases include:
  • authentication flows
  • user self-registration
  • password change or reset
  • self-services (e.g. registering new tokens)
Loginapp REST API consists of two parts: a set of publicly available services and a set of protected services which can only be accessed by authenticated end-users.

Further services will be continuously added in upcoming releases.

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 a delegating entity 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.

Authentication API

An important part of the Loginapp REST API is the authentication API. It is located under the /authentication/ path in the public subtree. A detailed documentation of the various endpoints can be found by browsing the resource tree on the right. The endpoints' documentation includes the structure of the response body in non-error cases. If errors occur (e.g. the user provides a wrong password), the responses follow the generic format described above.

Authentication flow model

When multiple steps are required for a client to successfully authenticate, the authentication API provides hints about a possible next step in the flow. This is the case in regular responses (e.g. second factor required) as well as error responses (e.g. retry after wrong password). The next step is communicated to the client in an attribute called nextAuthStep. The location of this attribute within the response depends on the response type (regular or error response).

Successful response

This is an example response of a successful first authentication step with username and password. The value MTAN_OTP_REQUIRED of nextAuthStep tells the client, that an MTAN OTP must be provided in order to continue the authentication process.
{
  "meta": {
    "type": "jsonapi.metadata.document",
    "timestamp": "2016-04-26T07:41:05.697+00:00"
  },
  "data": {
    "type": "authentication.session",
    "id": "1234",
    "attributes": {
      "nextAuthStep": "MTAN_OTP_REQUIRED",
      "resendPossible": true,
      "phoneNumber": "+41791234567"
    },
    "links": {
      "self": "https://www.airlock.com/auth-login/rest/public/authentication/password/check"
    }
  }
}

Failing response

In error responses, the next step is communicated to the client in a meta attribute that is also called nextAuthStep.

Client error response

The snippet below shows the response of a failed first factor check. Username and/or password was wrong, which is indicated by the error code USERNAME_PASSWORD_WRONG. The meta attribute nextAuthStep with value PASSWORD_REQUIRED tells the client that he should try again to authenticate with the password check step.
{
  "meta": {
    "type": "jsonapi.metadata.document",
    "timestamp": "2016-04-26T07:47:23.578+00:00",
    "temporaryLockExpiry": "2016-04-26T07:47:27.578+00:00",
    "nextAuthStep": "PASSWORD_REQUIRED"
  },
  "errors": [
    {
      "id": "3565:9954",
      "status": 400,
      "code": "USERNAME_PASSWORD_WRONG"
    }
  ]
}
If the user has been locked out temporarily as a result of the failed factor check, the meta attribute temporaryLockExpiry contains the point in time when the lock will expire. All authentication requests for the user in question before that time, will be rejected with the error code USER_TEMPORARILY_LOCKED.

Next Auth Step Codes

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

nextAuthStep Code Possible next call(s)
ACCESS_CALL_REQUIRED POST /public/authentication/applications/{applicationId}/access/
POST /public/authentication/default-application/access/
POST /public/authentication/location/access/
(typically with credentials in the Authorization header.)
AIRLOCK_2FA_DEVICE_ACTIVATION_POLLING_REQUIRED POST /public/authentication/airlock-2fa/activation/status/poll/
AIRLOCK_2FA_DEVICE_ACTIVATION_REQUIRED POST /public/authentication/airlock-2fa/activation/challenge/retrieve/
AIRLOCK_2FA_DEVICE_CHOICE_REQUIRED POST /public/authentication/airlock-2fa/devices/retrieve/
POST /public/authentication/airlock-2fa/devices/{deviceId}/select/
AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE POST /public/authentication/airlock-2fa/activation/device-edit/data/
POST /public/authentication/airlock-2fa/activation/device-edit/continue/
AIRLOCK_2FA_MOBILE_ONLY_CHALLENGE_RETRIEVAL_REQUIRED POST /public/authentication/airlock-2fa/mobile-only/challenge/retrieve/
AIRLOCK_2FA_PASSCODE_OR_QR_CODE_OTP_REQUIRED POST /public/authentication/airlock-2fa/passcode/check/
POST /public/authentication/airlock-2fa/offline-qr-code/challenge/retrieve/
AIRLOCK_2FA_PASSCODE_REQUIRED POST /public/authentication/airlock-2fa/passcode/check/
AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED POST /public/authentication/airlock-2fa/status/poll/
POST /public/authentication/airlock-2fa/offline/
AIRLOCK_2FA_POLLING_REQUIRED POST /public/authentication/airlock-2fa/status/poll/
AIRLOCK_2FA_QR_CODE_OTP_REQUIRED POST /public/authentication/airlock-2fa/offline-qr-code/challenge/retrieve/
POST /public/authentication/airlock-2fa/offline-qr-code/otp/check/
CRONTO_ACTIVATION_COMPLETE_REQUIRED POST /public/authentication/cronto/activation/challenge/retrieve/
POST /public/authentication/cronto/activation/complete/
CRONTO_ACTIVATION_START_REQUIRED POST /public/authentication/cronto/activation/start/
CRONTO_ACTIVATION_START_WITHOUT_LETTER_REQUIRED POST /public/authentication/cronto/activation/start-challenge/retrieve/
POST /public/authentication/cronto/activation/start/
CRONTO_DEVICE_CHOICE_REQUIRED POST /public/authentication/cronto/push-devices/retrieve/
POST /public/authentication/cronto/push-devices/{id}/select/
POST /public/authentication/cronto/offline/
CRONTO_OTP_REQUIRED POST /public/authentication/cronto/challenge/retrieve/
POST /public/authentication/cronto/otp/check/
POST /public/authentication/cronto/otp/poll/ (if online validation active)
CRONTO_PUSH_ACTIVATION_POSSIBLE POST /public/authentication/cronto/push-devices/activation/challenge/retrieve/
POST /public/authentication/cronto/push-devices/activation/continue/
POST /public/authentication/cronto/push-devices/activation/skip/
POST /public/authentication/cronto/push-devices/activation/never/
DEVICE_TOKEN_RESPONSE_REQUIRED POST /public/authentication/device-token/{deviceTokenId}/challenge/retrieve/
POST /public/authentication/device-token/check/
EMAIL_OTP_CHECK_REQUIRED POST /public/authentication/email/otp/check/
POST /public/authentication/email/otp/resend/
EMAIL_OTP_REQUIRED POST /public/authentication/email/verification/otp/check/
FIDO_AUTHENTICATION_ASSERTION_RESPONSE_REQUIRED POST /public/authentication/fido/assertion-response/check/
FIDO_AUTHENTICATION_CHALLENGE_RETRIEVAL_REQUIRED POST /public/authentication/fido/challenge/retrieve/
FIDO_REGISTRATION_ATTESTATION_RESPONSE_REQUIRED POST /public/authentication/fido/registration/attestation-response/check/
FIDO_REGISTRATION_CHALLENGE_RETRIEVAL_REQUIRED POST /public/authentication/fido/registration/challenge/retrieve/
MANDATORY_PASSWORD_CHANGE POST /public/authentication/password/change/
MATRIX_RESPONSE_REQUIRED POST /public/authentication/matrix/challenge/retrieve/
POST /public/authentication/matrix/check/
MESSAGE_ACKNOWLEDGMENT_REQUIRED POST /public/authentication/message/acknowledge/
MIGRATION_SELECTION_REQUIRED POST /public/authentication/migration/options/retrieve/
POST /public/authentication/migration/options/{id}/select/
POST /public/authentication/migration/options/skip/
POST /public/authentication/migration/options/reject/
MTAN_OTP_REQUIRED POST /public/authentication/mtan/otp/check/
POST /public/authentication/mtan/otp/resend-info/retrieve/
POST /public/authentication/mtan/otp/resend/
MTAN_REGISTRATION_IAK_REQUIRED POST /public/authentication/mtan/registration/iak/check/
MTAN_REGISTRATION_OTP_REQUIRED POST /public/authentication/mtan/registration/otp/check/
MTAN_REGISTRATION_START_REQUIRED POST /public/authentication/mtan/registration/start/
MTAN_TOKEN_CHOICE_REQUIRED POST /public/authentication/mtan/tokens/retrieve/
POST /public/authentication/mtan/tokens/{id}/select/
NAVIGATION_REQUIRED Client (e.g. web-browser) is required to perform top-level navigation to the URI defined by the location attribute.
NEXT_OATH_OTP_REQUIRED POST /public/authentication/oath/otp/check/
NEXT_OTP_REQUIRED POST /public/authentication/otp/check/
OATH_OTP_REQUIRED POST /public/authentication/oath/otp/check/
OAUTH2_AUTHORIZATION_SERVER_LOCAL_CONSENT_REQUIRED POST /public/authentication/oauth2/authorization-server/consent/local/retrieve/
POST /public/authentication/oauth2/authorization-server/consent/local/grant/
OAUTH2_AUTHORIZATION_SERVER_REMOTE_CONSENT_REQUIRED POST /public/authentication/oauth2/authorization-server/consent/remote/check/
OAUTH2_CLIENT_AUTHORIZATION_REQUIRED POST /public/authentication/oauth2/client/authorization/check/
OTP_REQUIRED POST /public/authentication/otp/check/
PASSWORD_CHANGE_REQUIRED POST /public/authentication/password/change/
PASSWORD_REQUIRED POST /public/authentication/password/check/
PASSWORD_ONLY_REQUIRED POST /public/authentication/password-only/check/
SECRET_QUESTIONS_PROVISIONING_REQUIRED POST /public/authentication/secret-questions/status/retrieve/
POST /public/authentication/secret-questions/provision/
SELECTION_REQUIRED POST /public/authentication/selection/options/retrieve/
POST /public/authentication/selection/options/{id}/select/
SSI_CREDENTIAL_ACCEPTANCE_REQUIRED
 INCUBATING
POST /public/authentication/ssi/issuance/poll/
SSI_PROOF_VERIFICATION_REQUIRED
 INCUBATING
POST /public/authentication/ssi/verification/poll/
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
POST /public/authentication/ssi/invitation/poll/
TERMS_OF_SERVICES_ACCEPT_REQUIRED POST /public/authentication/terms-of-services/accept-retrieved/
POST /public/authentication/terms-of-services/deny-retrieved/
TERMS_OF_SERVICES_RETRIEVAL_REQUIRED POST /public/authentication/terms-of-services/retrieve/
USER_DATA_EDIT_POSSIBLE
All user data validates. The flow can be continued or further edits can be performed.
POST /public/authentication/data/info/retrieve/
POST /public/authentication/data/edit/
POST /public/authentication/data/validate/
POST /public/authentication/data/continue/
USER_DATA_EDIT_REQUIRED
Some user data is not yet valid, further edits are required before the flow can be continued.
POST /public/authentication/data/info/retrieve/
POST /public/authentication/data/edit/
POST /public/authentication/data/validate/
USERNAME_REQUIRED POST /public/authentication/username/identify/
VASCO_OTP_REQUIRED POST /public/authentication/vasco/otp/check/

Additional attributes in authentication flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type authentication.session or to the meta data of error responses. The possible attributes depend on the content of the response:

Response Additional Attribute Type Description/Comment
nextAuthStep: AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE displayName string Indicates the current display name of the newly activated Airlock 2FA device (which can be changed using POST /public/authentication/airlock-2fa/activation/device-edit/data/)
nextAuthStep: EMAIL_OTP_CHECK_REQUIRED resendPossible boolean Indicates whether resending the email can be requested (using POST /public/authentication/email/otp/resend/)
nextAuthStep: EMAIL_OTP_REQUIRED
EMAIL_OTP_CHECK_REQUIRED
emailAddress string The email address the OTP was sent to. Depending on the configuration, this value is masked.
nextAuthStep: MATRIX_RESPONSE_REQUIRED matrixChallenges string array The matrix card challenges the client must answer (using POST /public/authentication/matrix/check/)
nextAuthStep: MESSAGE_ACKNOWLEDGMENT_REQUIRED messageId string Indicates which pre-configured message ID needs to be handled and acknowledged by a client (using POST /public/authentication/message/acknowledge/). One of the attributes messageId and serverMessage is guaranteed to be present.
nextAuthStep: MESSAGE_ACKNOWLEDGMENT_REQUIRED serverMessage string The server-generated message that needs to be acknowledged by a client (using POST /public/authentication/message/acknowledge/). One of the attributes messageId and serverMessage is guaranteed to be present.
nextAuthStep: MTAN_OTP_REQUIRED resendPossible boolean Indicates whether resending the SMS can be requested (using POST /public/authentication/mtan/otp/resend/)
nextAuthStep: MTAN_OTP_REQUIRED phoneNumber string The phone number the mTAN OTP was sent to. Depending on the configuration, this value is masked.
nextAuthStep: MTAN_REGISTRATION_OTP_REQUIRED resendPossible boolean Indicates whether resending the SMS can be requested (using POST /public/authentication/mtan/registration/otp/resend/)
nextAuthStep: MTAN_REGISTRATION_OTP_REQUIRED phoneNumber string The phone number the mTAN OTP was sent to. Depending on the configuration, this value is masked.
nextAuthStep: NAVIGATION_REQUIRED location string Contains the absolute URI to which the client (e.g. web-browser) is required to perform top-level navigation.
nextAuthStep: OAUTH2_AUTHORIZATION_SERVER_LOCAL_CONSENT_REQUIRED consent object Provides data about the grantable scopes for the OAuth 2.0 client. The object typically has the following structure:
  • clientName (string): the name of the OAuth 2.0 client
  • grantableScopes (object array): the list of grantable scopes
    • scope (string): the technical scope name
    • translatedScope (string): an optional human-readable version of this scope for the current locale.
nextAuthStep: OAUTH2_AUTHORIZATION_SERVER_REMOTE_CONSENT_REQUIRED consent object Provides data about the consent grant process. The object typically has the following structure:
  • redirectUrl (string): the URL of remote site which performs the consent check
  • token (string): the consent token (encrypted and signed JWT) with the relevant data for the remote site
nextAuthStep: OAUTH2_CLIENT_AUTHORIZATION_REQUIRED authorizationRequestUri string The Authorization Request URI to use to initiate the OAuth 2.0 / OpenID Connect handshake on the authorization server. The authorization response from the server must be verified (using POST /public/authentication/oauth2/client/authorization/check/).
nextAuthStep: OTP_REQUIRED emailAddress string If email is used as OTP method, includes the email address the OTP was sent to. Otherwise, the attribute is not present. Depending on the configuration, this value is masked.
nextAuthStep:
PASSWORD_REQUIRED
MANDATORY_PASSWORD_CHANGE
PASSWORD_ONLY_REQUIRED
e2eEncryptionInformation object Provides additional information necessary (e.g. a nonce) for the client to be able to end-to-end encrypt a password when authenticating. The content is implementation-specific. This additional attribute is present if end-to-end encryption is activated on the current flow step.
nextAuthStep: SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationLink string The invitation link allowing the holder wallet to establish a connection to the SSI service.
nextAuthStep: SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationQrCode string Base64-encoded QR code containing the invitation link.
Error code: USER_LOCKED lockReasonAllowsSelfUnlock boolean Indicates whether user self-unlock is supported by the current lock reason of the user. Certain lock reasons do not allow a user to perform a self-unlock. The availability of an actual self-unlock flow is however dependent on the configuration.
Error code:
OAUTH2_AUTHORIZATION_SERVER_AUTHORIZATION_FAILED
OAUTH2_AUTHORIZATION_SERVER_INVALID_AUTHORIZATION_REQUEST
clientRedirectUri string The Authorization Response Error URI to use to redirect back to the OAuth 2.0 / OpenID Connect client.
Any failed authentication factor check remainingFactorAttempts integer The number of remaining attempts on the just failed authentication factor before the user is locked (if this feature is enabled in the Authentication Flow configuration).
Any step result after an OpenID Connect authentication call:
POST /public/authentication/oauth2/authorization-servers/{authorizationServerId}/authorize/
uiLocale string The locale in the BCP47 [RFC5646] format the UI should be displayed in.
usernameHint string Hint about the username the client might use to authenticate.
Any non-failing step result after an identity providing step latestAuthentication object Provides data about the identified user's latest authentication attempt. The object typically contains two properties:
  • attemptAt (date-time): the timestamp of the latest authentication attempt
  • successful (boolean): whether the latest authentication attempt was successful
If the JSON object is empty, the feature is active but the identified user does not yet have any authentication attempts. This feature can be enabled in the authentication processors configuration.

Session Handling

The Authentication API currently relies on HTTP cookies to establish an authentication session between multiple authentication steps. I.e. clients of the API are required to support HTTP cookies.
Airlock Gateway also supports session tracking based on bearer tokens transported as HTTP headers.

Flow start

An authentication flow can be started explicitly by either calling the /public/authentication/applications/[applicationId]/access/ endpoint (if the application ID is known) or the /public/authentication/location/access endpoint (if the URL of the target application is known). If neither the application ID nor the target application URL is known, the default flow can be started by calling the /public/authentication/default-application/access/ endpoint. If no flow has been started in this manner, the first request to a flow endpoint automatically starts the default flow. This can be prevented (e.g. to avoid unintentially starting the wrong flow after a session timeout) by adding the request header X-Continue-Flow (with any value). If a request contains this header and no flow is currently active, an error response with status 403 and code NO_FLOW_TO_CONTINUE is returned.

Both "access" endpoints can be called with an SSO ticket attached to the request (as header or cookie, depending on the "SSO Ticket Extractor" configuration). This ticket will be available to all steps that are executed during this same request (typically the first step or all steps until the first interactive step). If the SSO or representation ticket step fails, the following error codes are possible:

  • SSO_TOKEN_MISSING: an SSO ticket is expected but could not be extracted from the request.
  • SSO_TOKEN_UNEXPECTED: an SSO ticket is not expected but was sent with this request.
  • SSO_TOKEN_VERIFICATION_FAILED: an SSO ticket could be extracted but was rejected (see logs for detailed reason).

If a Kerberos authentication step is configured in a flow, the "access" endpoint requests a WWW-Authenticate: Negotiate response header. In a Kerberos-enabled environment the browser repeats the request with the Authorization: Negotiate <Base64 encoded ticket> request header. If the Kerberos authentication step fails, the following error code is possible:

  • KERBEROS_TICKET_VERIFICATION_FAILED: the Kerberos ticket verification failed (see logs for detailed reason).

CAPTCHA

Public IAM REST endpoints can be protected from access by non-human clients (e.g. bots) using CAPTCHAs ("Completely Automated Public Turing test to tell Computers and Humans Apart").

Selected flow steps can be protected with a CAPTCHA. The REST endpoints for these steps are marked in the documentation with the CAPTCHA tag. When a CAPTCHA is required to be solved, a CAPTCHA challenge is present in the attributes of the REST response immediately preceeding the protected step:

  • If the first step in the flow is CAPTCHA-protected, this is typically the POST/protected/self-service/flows/{flowId}/select/ or POST/public/user-self-registration/flows/{flowId}/select/ endpoint.
  • If the CAPTCHA challenge doesn't have to be solved in the first step, the challenge will be in the additional attributes of the request from the previous step.

{
      "meta": {...},
      "data": {
        ...
        "attributes": {
          "captcha": {
            "type": ...
            // CAPTCHA challenge
            }
          ...
        }
      }
    }

The CAPTCHA solution is expected to be present in the X-Captcha-Solution header of the next REST request to a flow endpoint. If no solution header is present or the provided solution is wrong or has already been used or has timed out, an error response with status code 400 (Bad Request) and error code CAPTCHA_CHECK_FAILED is returned (as described in Client error response). If a CAPTCHA check fails, the user has more attempts and no failed attempts counter is incremented.

Two types of CAPTCHA challenges are currently supported: reCAPTCHA v2 ("I'm not a robot" Checkbox) and hCaptcha. For both types the challenge is represented by the site key. Please refer to the reCAPTCHA or the hCaptcha documentation for information on how to use the site key to solve a challenge.

Non-Browser implementations for reCAPTCHA (like the SafetyNet implementation) are not supported. In these use-cases, a browser window/viewer can be used to display the CAPTCHA challenge.

Maintenance Message

If a maintenance message is active indicating that the system is not available, the server responds with HTTP status code 503 - SERVICE UNAVAILABLE. In this case, the following endpoints are still available. This way the client can abort pending flows and terminate the user's session.
  • DELETE/protected/self-service/flow/
  • DELETE/public/authentication/
  • DELETE/public/authentication/flow/
  • DELETE/public/self-service/flow/
  • DELETE/public/user-self-registration/flow/

User Self-Registration API

Airlock IAM 7.0 introduces a flow-based REST API for user self-registration to facilitate flexible custom registration flows.
The endpoints are located under the /public/user-self-registration/ path. The API permits the registration of login names, password and context data and the verification of email addresses and phone numbers.

Next Self-Registration 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_ACTIVATION_POLLING_REQUIRED POST /public/user-self-registration/airlock-2fa/activation/status/poll/
AIRLOCK_2FA_DEVICE_ACTIVATION_REQUIRED POST /public/user-self-registration/airlock-2fa/activation/challenge/retrieve/
EMAIL_OTP_REQUIRED
POST /public/user-self-registration/verification/email/otp/check/
MESSAGE_ACKNOWLEDGMENT_REQUIRED POST /public/user-self-registration/message/acknowledge/
SELECTION_REQUIRED POST /public/user-self-registration/selection/options/retrieve/
POST /public/user-self-registration/selection/options/{id}/select/
SMS_OTP_REQUIRED
POST /public/user-self-registration/verification/phone-number/otp/check/
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
POST /public/user-self-registration/ssi/invitation/poll/
SSI_PROOF_VERIFICATION_REQUIRED
 INCUBATING
POST /public/user-self-registration/ssi/verification/poll/
TERMS_OF_SERVICES_ACCEPT_REQUIRED POST /public/user-self-registration/terms-of-services/accept-retrieved/
POST /public/user-self-registration/terms-of-services/deny-retrieved/
TERMS_OF_SERVICES_RETRIEVAL_REQUIRED POST /public/user-self-registration/terms-of-services/retrieve/
USER_DATA_REGISTRATION_POSSIBLE
The data registered for this step is consistent and all mandatory data has been provided.
Further registration calls are still possible, as is continuing to the next step.
POST /public/user-self-registration/registration/password/
POST /public/user-self-registration/registration/data/
POST /public/user-self-registration/registration/validate/
POST /public/user-self-registration/registration/continue/
USER_DATA_REGISTRATION_REQUIRED
The already registered data for this step is not yet consistent or mandatory data is still missing.
More data registration calls are necessary before continuing to the next step is possible.
POST /public/user-self-registration/registration/password/
POST /public/user-self-registration/registration/data/
POST /public/user-self-registration/registration/validate/

Additional attributes in user self-registration flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type user-self-registration.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
EMAIL_OTP_REQUIRED emailAddress string The email address the OTP was sent to. Depending on the configuration, this value is masked.
MESSAGE_ACKNOWLEDGMENT_REQUIRED messageId string Indicates which pre-configured message ID needs to be handled and acknowledged by a client (using POST /public/user-self-registration/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 /public/user-self-registration/message/acknowledge/). One of the attributes messageId and serverMessage is guaranteed to be present.
SMS_OTP_REQUIRED phoneNumber string The phone number the SMS OTP was sent to. Depending on the configuration, this value is masked.
USER_DATA_REGISTRATION_POSSIBLE
USER_DATA_REGISTRATION_REQUIRED
e2eEncryptionInformation object Provides additional information necessary (e.g. a nonce) for the client to be able to end-to-end encrypt a password for registration. The content is implementation-specific. This additional attribute is present if end-to-end encryption is activated on the current flow step and a password can be registered for the current step.
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationLink string The invitation link allowing the holder wallet to establish a connection to the SSI service.
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationQrCode string Base64-encoded QR code containing the invitation link.
Any step result preceeding a step that requires a CAPTCHA to be solved captcha object Provides the data and type of the CAPTCHA challenge that has to be solved:
  • key (string): the site key needed to display the challenge
  • type (string): the type of the challenge, either H_CAPTCHA or RE_CAPTCHA.

Public Self-Service API

This flow-based REST API allows unauthenticated users to perform self-services, e.g. a password reset after one or more verification steps. The endpoints are located under the /public/self-service/ path.

Next Public Self-Service 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 /public/self-service/approval/airlock-2fa/devices/retrieve/
POST /public/self-service/approval/airlock-2fa/devices/{id}/select/
AIRLOCK_2FA_MOBILE_ONLY_CHALLENGE_RETRIEVAL_REQUIRED POST /public/self-service/approval/airlock-2fa/mobile-only/challenge/retrieve/
AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED POST /public/self-service/approval/airlock-2fa/status/poll/
POST /public/self-service/approval/airlock-2fa/offline/
AIRLOCK_2FA_POLLING_REQUIRED POST /public/self-service/approval/airlock-2fa/status/poll/
AIRLOCK_2FA_QR_CODE_OTP_REQUIRED POST /public/self-service/approval/airlock-2fa/offline-qr-code/challenge/retrieve/
POST /public/self-service/approval/offline-qr-code/airlock-2fa/otp/check/
CRONTO_DEVICE_CHOICE_REQUIRED POST /public/self-service/approval/cronto/push-devices/retrieve/
POST /public/self-service/approval/cronto/push-devices/{id}/select/
POST /public/self-service/approval/cronto/offline/
DEVICE_TOKEN_RESPONSE_REQUIRED POST /public/self-service/device-token/{deviceTokenId}/challenge/retrieve/
POST /public/self-service/device-token/check/
CRONTO_OTP_REQUIRED POST /public/self-service/approval/cronto/challenge/retrieve/
POST /public/self-service/approval/cronto/otp/check/
POST /public/self-service/approval/cronto/otp/poll/ (if online validation active)
EMAIL_OTP_REQUIRED
POST /public/self-service/verification/email/otp/check/
MATRIX_RESPONSE_REQUIRED
POST /public/self-service/approval/matrix/challenge/retrieve/
POST /public/self-service/approval/matrix/check/
MESSAGE_ACKNOWLEDGMENT_REQUIRED POST /public/self-service/message/acknowledge/
MTAN_OTP_REQUIRED
POST /public/self-service/verification/mtan/otp/check/
POST /public/self-service/approval/mtan/otp/check/
POST /public/self-service/approval/mtan/otp/resend-info/retrieve/
POST /public/self-service/approval/mtan/otp/resend/
MTAN_TOKEN_CHOICE_REQUIRED POST /public/self-service/approval/mtan/tokens/retrieve/
POST /public/self-service/approval/mtan/tokens/{id}/select/
NEW_PASSWORD_REQUIRED
POST /public/self-service/password/set/
SECRET_QUESTIONS_ANSWER_REQUIRED
POST /public/self-service/verification/secret-questions/answer/
SELECTION_REQUIRED POST /public/self-service/selection/options/retrieve/
POST /public/self-service/selection/options/{id}/select/
SSI_PROOF_VERIFICATION_REQUIRED
 INCUBATING
POST /public/self-service/ssi/verification/poll
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
POST /public/self-service/ssi/invitation/poll
USERNAME_REQUIRED
POST /public/self-service/username/identify/

Additional attributes in public self-service flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type public-self-service.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
MATRIX_RESPONSE_REQUIRED matrixChallenges string array The matrix card challenges the client must answer (using POST /public/self-service/approval/matrix/check/)
MESSAGE_ACKNOWLEDGMENT_REQUIRED messageId string Indicates which pre-configured message ID needs to be handled and acknowledged by a client (using POST /public/self-service/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 /public/self-service/message/acknowledge/). One of the attributes messageId and serverMessage is guaranteed to be present.
MTAN_OTP_REQUIRED resendPossible boolean Indicates whether resending the SMS can be requested (using POST /public/self-service/approval/mtan/otp/resend/)
MTAN_OTP_REQUIRED phoneNumber string The phone number the mTAN OTP was sent to. Depending on the configuration, this value is masked.
NEW_PASSWORD_REQUIRED e2eEncryptionInformation object Provides additional information necessary (e.g. a nonce) for the client to be able to end-to-end encrypt the new password. The content is implementation-specific. This additional attribute is present if end-to-end encryption is activated on the current flow step.
stop representation flow representeeLogoutUri string Added by stop representation flows to indicate the logout URL on the representee IAM.
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationLink string The invitation link allowing the holder wallet to establish a connection to the SSI service.
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationQrCode string Base64-encoded QR code containing the invitation link.
Any step result preceeding a step that requires a CAPTCHA to be solved captcha object Provides the data and type of the CAPTCHA challenge that has to be solved:
  • key (string): the site key needed to display the challenge
  • type (string): the type of the challenge, either H_CAPTCHA or RE_CAPTCHA.

Self-Service Flow API

This flow-based REST API allows authenticated users to perform self-services, such as editing user data, changing their password or managing authentication tokens. The endpoints are located under the /protected/self-service/ path.

Next Self-Service 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_ACTIVATION_POLLING_REQUIRED POST /protected/self-service/airlock-2fa/activation/status/poll/
AIRLOCK_2FA_DEVICE_ACTIVATION_REQUIRED POST /protected/self-service/airlock-2fa/activation/challenge/retrieve/
AIRLOCK_2FA_DEVICE_CHOICE_REQUIRED POST /protected/self-service/airlock-2fa/devices/{deviceId}/select/
POST /protected/self-service/approval/airlock-2fa/devices/retrieve/
POST /protected/self-service/approval/airlock-2fa/devices/{id}/select/
AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE POST /protected/self-service/airlock-2fa/device-edit/data/
POST /protected/self-service/airlock-2fa/device-edit/continue/
AIRLOCK_2FA_DEVICE_REMOVAL_REQUIRED POST /protected/self-service/airlock-2fa/devices/{deviceId}/remove/
AIRLOCK_2FA_MOBILE_ONLY_CHALLENGE_RETRIEVAL_REQUIRED POST /protected/self-service/approval/airlock-2fa/mobile-only/challenge/retrieve/
AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED POST /protected/self-service/approval/airlock-2fa/status/poll/
POST /protected/self-service/approval/airlock-2fa/offline/
AIRLOCK_2FA_POLLING_REQUIRED POST /protected/self-service/approval/airlock-2fa/status/poll/
AIRLOCK_2FA_QR_CODE_OTP_REQUIRED POST /protected/self-service/approval/airlock-2fa/offline-qr-code/challenge/retrieve/
POST /protected/self-service/approval/airlock-2fa/offline-qr-code/otp/check/
CRONTO_ACTIVATION_COMPLETE_REQUIRED POST /protected/self-service/cronto/activation/challenge/retrieve/
POST /protected/self-service/cronto/activation/complete/
CRONTO_ACTIVATION_START_REQUIRED POST /protected/self-service/cronto/activation/start/
CRONTO_ACTIVATION_START_WITHOUT_LETTER_REQUIRED POST /protected/self-service/cronto/activation/start-challenge/retrieve/
POST /protected/self-service/cronto/activation/start/
CRONTO_DEVICE_CHOICE_REQUIRED POST /protected/self-service/approval/cronto/push-devices/retrieve/
POST /protected/self-service/approval/cronto/push-devices/{id}/select/
POST /protected/self-service/approval/cronto/offline/
CRONTO_DEVICE_DISABLING_REQUIRED POST /protected/self-service/cronto/devices/{id}/disable/
CRONTO_DEVICE_ENABLING_REQUIRED POST /protected/self-service/cronto/devices/{id}/enable/
CRONTO_DEVICE_REMOVAL_REQUIRED POST /protected/self-service/cronto/devices/{id}/remove/
CRONTO_DEVICE_RENAMING_POSSIBLE POST /protected/self-service/cronto/device/edit/
POST /protected/self-service/cronto/device/edit/continue/
CRONTO_DEVICE_RENAMING_REQUIRED POST /protected/self-service/cronto/device/edit/
CRONTO_DEVICE_SELECTION_REQUIRED POST /protected/self-service/cronto/devices/{id}/select/
CRONTO_OTP_REQUIRED POST /protected/self-service/approval/cronto/challenge/retrieve/
POST /protected/self-service/approval/cronto/otp/check/
POST /protected/self-service/approval/cronto/otp/poll/ (if online validation active)
CRONTO_PUSH_ACTIVATION_POSSIBLE POST /protected/self-service/cronto/push-devices/activation/challenge/retrieve/
POST /protected/self-service/cronto/push-devices/activation/continue/
CRONTO_PUSH_DISABLING_REQUIRED POST /protected/self-service/cronto/devices/{id}/push/disable/
CRONTO_PUSH_ENABLING_REQUIRED POST /protected/self-service/cronto/devices/{id}/push/enable/
EMAIL_OTP_REQUIRED
POST /protected/self-service/email/verification/otp/check/
FIDO_CREDENTIAL_DISABLING_REQUIRED POST /protected/self-service/fido/credentials/{credentialId}/disable/
FIDO_CREDENTIAL_EDIT_POSSIBLE POST /protected/self-service/fido/credential/edit/
FIDO_CREDENTIAL_ENABLING_REQUIRED POST /protected/self-service/fido/credentials/{credentialId}/enable/
FIDO_CREDENTIAL_REMOVAL_REQUIRED POST /protected/self-service/fido/credentials/{credentialId}/remove/
FIDO_CREDENTIAL_SELECTION_REQUIRED POST /protected/self-service/fido/credentials/{credentialId}/select/
FIDO_REGISTRATION_ATTESTATION_RESPONSE_REQUIRED POST /protected/self-service/fido/registration/attestation-response/check/
FIDO_REGISTRATION_CHALLENGE_RETRIEVAL_REQUIRED POST /protected/self-service/fido/registration/challenge/retrieve/
MATRIX_RESPONSE_REQUIRED
POST /protected/self-service/approval/matrix/challenge/retrieve/
POST /protected/self-service/approval/matrix/check/
MESSAGE_ACKNOWLEDGMENT_REQUIRED POST /protected/self-service/message/acknowledge/
MTAN_OTP_REQUIRED POST /protected/self-service/approval/mtan/otp/check/
POST /protected/self-service/approval/mtan/otp/resend-info/retrieve/
POST /protected/self-service/approval/mtan/otp/resend/
MTAN_REGISTRATION_IAK_REQUIRED POST /protected/self-service/mtan/registration/iak/check/
MTAN_REGISTRATION_OTP_REQUIRED POST /protected/self-service/mtan/registration/otp/check/
MTAN_REGISTRATION_START_REQUIRED POST /protected/self-service/mtan/registration/start/
MTAN_TOKEN_CHOICE_REQUIRED POST /protected/self-service/approval/mtan/tokens/retrieve/
POST /protected/self-service/approval/mtan/tokens/{id}/select/
MTAN_TOKEN_SELECTION_REQUIRED POST /protected/self-service/mtan/tokens/{tokenId}/select/
MTAN_TOKEN_EDIT_REQUIRED POST /protected/self-service/mtan/token/edit/
MTAN_TOKEN_EDIT_POSSIBLE POST /protected/self-service/mtan/token/edit/
POST /protected/self-service/mtan/token/edit/continue/
MTAN_TOKEN_REMOVAL_REQUIRED POST /protected/self-service/mtan/tokens/{tokenId}/remove/
OAUTH2_CLIENT_AUTHORIZATION_REQUIRED POST /protected/self-service/oauth2/client/authorization/check/
PASSWORD_CHANGE_REQUIRED POST /protected/self-service/password/change/
SELECTION_REQUIRED POST /protected/self-service/selection/options/retrieve/
POST /protected/self-service/selection/options/{id}/select/
SSI_CREDENTIAL_ACCEPTANCE_REQUIRED
 INCUBATING
POST /protected/self-service/ssi/issuance/poll/
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
POST /protected/self-service/ssi/invitation/poll/
USER_DATA_EDIT_POSSIBLE
All user data validates. The flow can be continued or further edits can be performed.
POST /protected/self-service/data/info/retrieve/
POST /protected/self-service/data/edit/
POST /protected/self-service/data/validate/
POST /protected/self-service/data/continue/
USER_DATA_EDIT_REQUIRED
Some user data is not yet valid, further edits are required before the flow can be continued.
POST /protected/self-service/data/info/retrieve/
POST /protected/self-service/data/edit/
POST /protected/self-service/data/validate/
USER_REPRESENTATION_START_REQUIRED POST /protected/self-service/representation/start/
VASCO_DEVICE_ACTIVATION_REQUIRED POST /protected/self-service/vasco/devices/{deviceId}/activate/

Additional attributes in self-service flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type self-service.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
AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE displayName string Indicates the current display name of the selected Airlock 2FA device (which can be changed using POST /protected/self-service/airlock-2fa/device-edit/data/)
CRONTO_DEVICE_RENAMING_POSSIBLE
CRONTO_DEVICE_RENAMING_REQUIRED
currentCrontoDeviceName string Indicates the current display name of the selected Cronto device (if present).
EMAIL_OTP_REQUIRED emailAddress string The email address the OTP was sent to. Depending on the configuration, this value is masked.
FIDO_CREDENTIAL_EDIT_POSSIBLE currentFidoCredentialDisplayName string Indicates the current display name of the selected FIDO credential.
MATRIX_RESPONSE_REQUIRED matrixChallenges string array Provides the matrix card challenges the client must answer (using POST /protected/self-service/approval/matrix/check/)
MESSAGE_ACKNOWLEDGMENT_REQUIRED messageId string Indicates which pre-configured message ID needs to be handled and acknowledged by a client (using POST /protected/self-service/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 /protected/self-service/message/acknowledge/). One of the attributes messageId and serverMessage is guaranteed to be present.
MTAN_OTP_REQUIRED resendPossible boolean Indicates whether resending the SMS can be requested (using POST /protected/self-service/approval/mtan/otp/resend/)
MTAN_OTP_REQUIRED phoneNumber string The phone number the mTAN OTP was sent to. Depending on the configuration, this value is masked.
MTAN_REGISTRATION_OTP_REQUIRED resendPossible boolean Indicates whether resending the SMS can be requested (using POST /protected/self-service/mtan/registration/otp/resend/)
MTAN_REGISTRATION_OTP_REQUIRED phoneNumber string The phone number the mTAN OTP was sent to. Depending on the configuration, this value is masked.
OAUTH2_CLIENT_AUTHORIZATION_REQUIRED authorizationRequestUri string The Authorization Request URI to use to initiate the OAuth 2.0 / OpenID Connect handshake on the authorization server. The authorization response from the server must be verified (using POST /protected/self-service/oauth2/client/authorization/check/).
PASSWORD_CHANGE_REQUIRED e2eEncryptionInformation object Provides additional information necessary (e.g. a nonce) for the client to be able to end-to-end encrypt the new password. The content is implementation-specific. This additional attribute is present if end-to-end encryption is activated on the current flow step.
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationLink string The invitation link allowing the holder wallet to establish a connection to the SSI service.
SSI_WALLET_CONNECTION_REQUIRED
 INCUBATING
invitationQrCode string Base64-encoded QR code containing the invitation link.
USER_REPRESENTATION_START_REQUIRED representeeLogoutUri string The logout URI the client should be redirected to in order to terminate any ongoing representee sessions. This redirect must be followed before starting a new representation session.
VASCO_DEVICE_ACTIVATION_REQUIRED activatableDevices list of objects Provides data about the activatable Vasco OTP devices. Each object has the following structure:
  • deviceId (string): the serial ID of a Vasco OTP device

Technical Client Registration API

This flow-based REST API allows the registration of technical clients such as OAuth 2.0 clients. The endpoints are located under the /public/tech-client-registration/ path.

Next Technical Client Registration Step Codes

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

nextStep Code Possible next call(s)
OAUTH2_CLIENT_DATA_REQUIRED
POST /public/tech-client-registration/oauth2/{authorizationServerId}/register/

OAuth 2.0 API

The OAuth 2.0 API provides various OAuth 2.0 and OpenID Connect endpoints. Many endpoints require an access token for authentication, which must be passed as a header parameter.

Loginapp 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.