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

Airlock IAM Adminapp 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 use-cases in the Adminapp REST API are designed for admin users only and should never be available to end-users (even with proper authentication). The network security policies for the Adminapp also apply for the Adminapp REST API.

The intended users of this API are internal systems (e.g. user management) or other back-end applications (e.g. password reset for an user). The interface constitutes an alternative to the Adminapp web UI. Example use-cases include:
  • create new user
  • lock/unlock an user
  • reset a user's password
  • change a user's authentication method

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.


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.


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:
  • 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
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
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

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
The corresponding pattern to be used in Java is

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


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).
  "meta": {
    "type": "jsonapi.metadata.document",
    "timestamp": "2016-04-25T13:57:26.122+00:00"
  "errors": [
      "id": "6117:5385",
      "status": 400,
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.
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.

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
USER_NOT_FOUND (400 / 403)
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:

  • 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
    "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

Query parameters
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 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.
Query parameter
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.

== (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.
Query parameter
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.


The REST API Configuration for the Adminapp is found in the "Adminapp" root node.

The access to the various REST calls is controlled by the plugins in the Admin Tool "Access Control" section. Services that are used by the Adminapp UI are hard-wired and only the required roles for each functionality have to be configured. Access to other REST calls (including custom extensions) can be configured using the section "REST Access Controller". It allows to define "Access Rules" for specific path patterns. They govern whether a user with a certain role set has access via some HTTP method to a given path.

Since the "Access Rules" are allow rules, only path pattern covered by an "Access Rule" can be accessed (white list). As roles are required to evaluate the "Access Rules", authentication should be mandatory for the (technical) administrator user accessing the API. "Authenticator" and "Request Credential Policy" plugins allow to configure how admin users are authenticated.

The role NO_RESTRICTION can be configured to grant access to anyone. Please refer to the documentation on the respective plugin for further information on its usage.

Adminapp REST call documentation

  • Deprecated.


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


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