Examples
17.2.2.3. Usage examples of REST authentication API

Example Flows

All requests send the following headers as specified in the Loginapp REST API Reference:

Headers

Content-Type: application/json
X-Same-Domain: 1

Application selection

If IAM protects multiple applications, the client can select an application to authenticate for.

Request

POST https://www.airlock.com/auth-login/rest/public/authentication/applications/{applicationId}/access/

Response

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-02-27T16:07:03.204+01:00",
        "nextAuthStep": "PASSWORD_REQUIRED"
    },
    "errors": [
        {
            "id": "3204:9542",
            "status": 401,
            "code": "NOT_AUTHORIZED"
        }
    ]
}

The response tells the client that access to the desired application is not yet granted and that verifying a password is expected as the next step.

Two-factor authentication: password and Airlock 2FA

Example showing two-factor authentication using password verification followed by Airlock 2FA One-Touch authentication.

Request

POST https://www.airlock.com/auth-login/rest/public/authentication/password/check/
{
	"username": "alice",
	"password": "password1"
}

Response

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T09:28:38.982+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "551431015764101535",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED"
        }
    }
}

The response indicates that the password was correct and that the next step in the authentication flow (nextAuthStep) is an Airlock 2FA step. The Loginapp REST API Reference specifies what REST call is expected given a next step attribute.

The next request asks for the authentication status before the user approved the authentication on the smartphone. It, therefore, asks the REST client to check the status again (or switch to offline mode).

Request

POST https://www.airlock.com/auth-login/rest/public/public/authentication/airlock-2fa/status/poll/

Response

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T09:40:15.227+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "537531808457366789",
        "attributes": {
            "nextAuthStep": "AIRLOCK_2FA_POLLING_OR_OFFLINE_REQUIRED"
        }
    }
}

The next request is the same as the one above but is sent after the user has approved the authentication request on the smartphone.

Request

POST https://www.airlock.com/auth-login/rest/public/public/authentication/airlock-2fa/status/poll/

Response

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T09:40:42.751+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "537531808457366789",
        "attributes": {}
    }
}

The response has status 200 - OK and defines no next authentication steps. The user is successfully authenticated.

Two-factor authentication: password and mTAN

Example showing two-factor authentication using password verification followed by mTAN (SMS-based one-time tokens).

Request

POST https://www.airlock.com/auth-login/rest/public/authentication/password/check/
{
	"username": "alice",
	"password": "password1"
}

Response

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-02-27T16:05:21.882+01:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "68088590",
        "attributes": {
            "nextAuthStep": "MTAN_OTP_REQUIRED"
        }
    }
}

The response indicates that the password was correct and that the next step in the authentication flow (nextAuthStep) is MTAN_OTP_REQUIRED. The Loginapp REST API Reference specifies what REST call is expected given a next step attribute.

The next request sends an incorrect mTAN OTP (because Alice did not correctly type the OTP):

Request

POST https://www.airlock.com/auth-login/rest/public/authentication/mtan/otp/check/
{
	"otp": "Kea72HiU"
}

Response

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-02-27T16:07:03.204+01:00",
        "nextAuthStep": "MTAN_OTP_REQUIRED"
    },
    "errors": [
        {
            "id": "3204:9542",
            "status": 400,
            "code": "MTAN_OTP_WRONG"
        }
    ]
}

Because of the wrong OTP, the following error response is shown. The configuration allows one retry of the OTP, therefore the nextAuthStep is still MTAN_OTP_REQUIRED. Without retries, the response would have the status 403 to indicate that the authentication failed definitely (see 16.8. flow error handling).

This time the request contains the correct and expected OTP:

Request

POST https://www.airlock.com/auth-login/rest/public/authentication/mtan/otp/check/
{
	"otp": "Kea72HiU"
}

Response

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-02-27T16:07:43.698+01:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "532202008",
        "attributes": {}
    }
}

The response has status 200 - OK and defines no next authentication steps. The user is successfully authenticated.