Airlock IAM Transaction Approval REST API

General information (for all IAM REST APIs)

Introduction to the Airlock IAM REST API

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)

Scope

Implementation and Integration

JSON:API format

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

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/

URIs

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

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

2011-12-03T10:15:30.000+01:00
2018-02-06T15:58:53.661Z

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.

2011-12-03

yyyy-MM-dd

API changes and versioning

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

Incubating features

Charset and Encoding

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

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

Error Responses

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"
    }
  ]
}

404 (NOT FOUND) response

• 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

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

503 (SERVICE UNAVAILABLE) response

Errors on updating relationships

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.

{
    "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"
            }
        }
    ]
}

Request Query Parameters

Paging

Query parameters

page[limit]
page[offset]

Limit/Size

Offset

Example (without URL encoding):

Filtering

Query parameter

filter

Syntax

• 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

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

Example (without URL encoding):

Sorting

Query parameter

sort

Syntax

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.

Example (without URL encoding):

Configuration Contexts

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

Flow control and flow status

Fundamentals

Starting flows

Ending flows

Interpretation of responses from flow endpoints

Flow-driving endpoints

Example

{
  ...
  "data": {
    "type": "authentication.session",
    "id": "1234",
    "attributes": {
      "nextAuthStep": "MTAN_OTP_REQUIRED",
      "resendPossible": true,
      "phoneNumber": "+41791234567"
    }
  }
}

Response status codes

Data retrieval endpoints

Example

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

Transaction Approval API

Next Approval Step Codes

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

Additional attributes in transaction approval flow responses

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

Transaction Approval REST call documentation