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": "Kea73HiU"
}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 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.