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

Airlock IAM Loginapp REST API

The intended users of the Loginapp REST API are end-users of Airlock IAM. Typical use-cases include:
  • authentication flows
  • changing their own password
  • user self-registration
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 two parts. The "Adminapp REST API" that offers an alternative interface for the Adminapp and the "Loginapp REST API" that offers end-user use cases such as authentication and user self-services.

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.

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 login 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.
  • 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)
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'.

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 e-mail- 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"
    },
    "links": {
      "self": "https://www.airlock.com/auth-login/rest/public/authentication/password/check"
    }
  }
}
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)
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)
DEVICE_TOKEN_RESPONSE_REQUIRED POST /public/authentication/device-token/{deviceTokenId}/challenge/retrieve/
POST /public/authentication/device-token/check/
KOBIL_TMS_DEVICE_CHOICE_REQUIRED POST /public/authentication/kobil-tms/devices/list
POST /public/authentication/kobil-tms/devices/{id}/select
KOBIL_TMS_POLLING_REQUIRED POST /public/authentication/kobil-tms/transaction/poll
POST /public/authentication/kobil-tms/transaction/restart
MANDATORY_PASSWORD_CHANGE POST /public/authentication/password/change/
MATRIX_RESPONSE_REQUIRED POST /public/authentication/matrix/challenge/retrieve/
POST /public/authentication/matrix/check/
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_TOKEN_CHOICE_REQUIRED POST /public/authentication/mtan/tokens/retrieve/
POST /public/authentication/mtan/tokens/{id}/select/
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/
OTP_REQUIRED POST /public/authentication/otp/check/
PASSWORD_REQUIRED POST /public/authentication/password/check/
SELECTION_REQUIRED POST /public/authentication/selection/options/retrieve/
POST /public/authentication/selection/options/{id}/select/
VASCO_OTP_REQUIRED POST /public/authentication/vasco/otp/check/
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_ACTIVATION_COMPLETE_REQUIRED POST /public/authentication/cronto/activation/challenge/retrieve/
POST /public/authentication/cronto/activation/complete/
TERMS_OF_SERVICES_RETRIEVAL_REQUIRED POST /public/authentication/terms-of-services/retrieve/
TERMS_OF_SERVICES_ACCEPT_REQUIRED POST /public/authentication/terms-of-services/accept-retrieved/
POST /public/authentication/terms-of-services/deny-retrieved/
SECRET_QUESTIONS_PROVISIONING_REQUIRED POST /public/authentication/secret-questions/status/retrieve/
POST /public/authentication/secret-questions/provision/

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.
In a future version of Airlock IAM, the API will alternatively support bearer tokens transported as HTTP header.

CAPTCHA

Public calls of the Loginapp REST API can be protected with a CAPTCHA. CAPTCHAs have to be enabled globally in the configuration. Additionally, a list of REST paths to be protected by CAPTCHAs must be provided in the configuration.

A POST to /public/captcha returns a challenge image to be displayed in the client. The server holds the solution and in the next call to a CAPTCHA-protected REST path, the provided solution is compared to the expected solution. The solution must be provided by the client in the HTTP header IAM-CAPTCHA-Solution of the request. Furthermore, the client must send the HTTP header IAM-CAPTCHA-Context, where the value must be provided, that was retrieved in the response of the POST to /public/captcha.
If a request to a CAPTCHA-protected resource fails to provide the required (and correct) header values, an error response with status code 400 (Bad Request) and error code CAPTCHA_CHECK_FAILED is returned.
CAPTCHAs are bound to the client's HTTP session. Therefore, in order to verify a CAPTCHA, the client must send its session cookie along with the request.
The CAPTCHA resource /public/captcha itself is excluded from CAPTCHA protection and can always be accessed.

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 e-mail 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)
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/
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/
EMAIL_OTP_REQUIRED
The OTP sent by e-mail has to be checked.
POST /public/user-self-registration/verification/email/otp/check/
SMS_OTP_REQUIRED
The OTP sent by SMS has to be checked.
POST /public/user-self-registration/verification/phone-number/otp/check/
TERMS_OF_SERVICES_RETRIEVAL_REQUIRED POST /public/user-self-registration/terms-of-services/retrieve/
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/
SELECTION_REQUIRED POST /public/user-self-registration/selection/options/retrieve/
POST /public/user-self-registration/selection/options/{id}/select/

Passwort Reset API

This flow-based REST API allows users to reset their passwords after one or more verification steps, e.g. e-mail OTP. The endpoints are located under the /public/password-reset/ path.

Next Password Reset Step Codes

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

nextStep Code Possible next call(s)
USERNAME_REQUIRED
A username must be provided.
POST /public/password-reset/username/identify
EMAIL_OTP_REQUIRED
The OTP sent by e-mail has to be checked.
POST /public/password-reset/verification/email/otp/check/
MTAN_OTP_REQUIRED
The OTP sent by SMS has to be checked.
POST /public/password-reset/verification/mtan/otp/check/
SECRET_QUESTIONS_ANSWER_REQUIRED
The secret questions asked need to be answered and checked.
POST /public/password-reset/verification/secret-questions/answer/
NEW_PASSWORD_REQUIRED
The new password can be set.
POST /public/password-reset/password/set/
SELECTION_REQUIRED POST /public/password-reset/selection/options/retrieve/
POST /public/password-reset/selection/options/{id}/select/

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)
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_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)
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_TOKEN_CHOICE_REQUIRED POST /protected/self-service/approval/mtan/tokens/retrieve/
POST /protected/self-service/approval/mtan/tokens/{id}/select/
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
SELECTION_REQUIRED POST /public/self-service/selection/options/retrieve/
POST /public/self-service/selection/options/{id}/select/

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/

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.