Use case

Usage - protected self-service flows REST API

This page shows how the REST API of the protected self-service flows can be used. It uses the address-change flow from the demo configuration as an example.

Prerequisite

  • The protected self-service REST API requires an authenticated session to be accessible.

Starting a protected self-service flow

To start a protected self-service flow the following REST resource is used:

<loginapp-uri>/rest/protected/self-service/flows/{flowId}/select/

<loginapp-uri>

This part of the URI depends on the deployment, Airlock Gateway (WAF) configuration and/or IAM instance configuration.

{flowId}

This parameter identifies the flow and the name is configurable.

Starting a protected self-service flow

A protected self-service flow follows the rules of the flow architecture and can be started like any other flow.

  • The status code must return 200 OK.
  • Every response to a REST API call will return a nextStep parameter to indicate if all conditions of the current step are met so that the flow can continue to the next step.
  • A response with status code 200 OK and without nextStep parameter declares the flow as successfully completed.

REST call sequence

The following REST call sequence shows how to use the protected self-service REST API from a REST client's point of view.

This example will use the following sequence:

  1. Authentication of the User
  2. Select and initiate the flow
  3. Retrieve the context data (e.g. to prefill the UI)
  4. Update context data
  5. Continue the flow
  6. Validate the update with mTAN/OTP check

Step 1 - HTTP Request - Authentication step

copy
POST /rest/public/authentication/password/check/
{
    "username" : "jdoe",
    "password" : "secret1!"
}

Step 1 - HTTP Response - Authentication step

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-26T09:36:22.835Z"
    },
    "data": {
        "type": "authentication.session",
        "id": "550116621426311805",
        "attributes": {}
    }

Step 2 - HTTP Request - Select and start the flow with id "address-change"

copy
POST /rest/protected/self-service/flows/address-change/select/

Step 2 - HTTP Response - Start the flow with id "address-change"

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-26T09:42:41.943Z"
    },
    "data": {
        "type": "self-service.session",
        "id": "550116621426311805",
        "attributes": {
            "nextStep": "USER_DATA_EDIT_POSSIBLE"
        }
    }

Step 3 - HTTP Request - Retrieve data from the user

copy
POST /rest/protected/self-service/data/info/retrieve/

Step 3 - HTTP Response - Retreive data from the user

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-09-21T10:51:38.168Z"
    },
    "data": [
        {
            "type": "self-service.data-edit-item-info",
            "id": "street",
            "attributes": {
                "currentValue": "Merkurstrasse",
                "required": false,
                "itemType": "string"
            }
        },
        {
            "type": "self-service.data-edit-item-info",
            "id": "streetNumber",
            "attributes": {
                "currentValue": "43",
                "required": false,
                "itemType": "string"
            }
        },
        {
            "type": "self-service.data-edit-item-info",
            "id": "zipcode",
            "attributes": {
                "currentValue": "CH-8032",
                "required": false,
                "itemType": "string",
                "additionalValidations": [
                    {
                        "type": "regex",
                        "caseSensitive": true,
                        "pattern": "[0-9]+"
                    }
                ]
            }
        },
        {
            "type": "self-service.data-edit-item-info",
            "id": "town",
            "attributes": {
                "currentValue": "Zuerich",
                "required": false,
                "itemType": "string"
            }
        }
    ]
}

Step 4 - HTTP Request - Update context data

copy
POST /rest/protected/self-service/data/edit/
{
    "zipcode": "8032" ,
    "town": "Zürich"
}

Step 4 - HTTP Response - Update context data

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-26T09:45:33.700Z"
    },
    "data": {
        "type": "self-service.session",
        "id": "550116621426311805",
        "attributes": {
            "nextStep": "USER_DATA_EDIT_POSSIBLE"
        }
    }
}

Step 5 - HTTP Request - Complete data/edit with continue

copy
POST /rest/protected/self-service/data/continue/

Step 5 - HTTP Response - Complete data/edit with continue

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-26T09:50:24.941Z"
    },
    "data": {
        "type": "self-service.session",
        "id": "550116621426311805",
        "attributes": {
            "nextStep": "MTAN_OTP_REQUIRED"
        }
    }
}

Step 6 - HTTP Request - Validate data/edit with mtan/otp/check

copy
POST /rest/protected/self-service/approval/mtan/otp/check/
{
    "otp" : "123456"
}

Step 6 - HTTP Response - Validate data/edit with mtan/otp/check

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-03-26T09:52:15.857Z"
    },
    "data": {
        "type": "self-service.session",
        "id": "550116621426311805",
        "attributes": {}
    }
}