Auth API

The purpose of the Auth API is to handle consumer's state and if needed the input, too. Whenever consumer input is needed the associated XS2A Form can be retrieved over this API and the response to this form is sent to this API as well.

In most cases the Auth API will be accessed by the XS2A App, but in a white label integration the Auth API is called from the TPP/merchant.

The URL for the Auth API is always dependent on a Flow and can therefore be obtained from the auth_url-field in the client_token that is part of the response when starting a Flow.

Optional available headers for Auth API endpoints:

User-Agent: The user agent from the customer
Client-Agent: A service version from your integration

Fetching the current State from the Auth API

The current state can always be retrieved by calling the Auth API endpoint via GET.

GET <decoded(client_token).auth_url> HTTP/1.1
Host: <Host>

curl -X "GET" "<decoded(client_token).auth_url>"

Result of a successful GET-call

{
    "data": {
        "state": Enum<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'FINISHED', 'ABORTED', 'EXCEPTION'>,
        "next": ?URL,
        "result": ...
    }
}

The result property

Response structure if result.type is bank_search

{
    "data": {
        "state": "CONSUMER_INPUT_NEEDED",
        "next": String,
        "result": {
            "type": "bank_search",
            "configuration": {
                "allowed_countries": Array<String>,
                "preselected_country": String
            },
            "context": "bank_selection"
        }
    }
}

Response structure if result.type is form

{
    "data": {
        "state": "PROCESSING | CONSUMER_INPUT_NEEDED",
        "next": String,
        "result": {
            "type":  "form",
            "form": XS2AForm,
            "key": String,
            "context": Enum< "transport_selection", "authentication_method_selection", "authentication", "account_selection", "authorization_method_selection", "authorization", "none">
        }
    }
}

The response of the type form is the payload that is present in most cases.

Response structure if result.type is redirect

{
    "data": {
        "state": "CONSUMER_INPUT_NEEDED",
        "next": URL,
        "result": {
            "type":  "redirect",
            "redirect": {
                "url": URL,
                "id": String
            },
            "context": Enum< "authentication", "authorization">
        }
    }
}

Response structure if result.type is error

{
    "data": {
        "state": "EXCEPTION",
        "next": URL,
        "result": {
            "type": "error",
            "category": String,
            "message": String,
            "context": Enum<"bank_selection", "transport_selection", "authentication_method_selection", "authentication", "account_selection", "authorization_method_selection", "authorization", "none">
        }
    }
}

Example Response for a successful GET-call

{
    "data": {
        "state": "CONSUMER_INPUT_NEEDED",
        "next": "https://authapi.openbanking.klarna.com/xs2a/v1/wizard/1234567890123456789",
        "result": {
            "type": "form",
            "form": {
                "version": "1.0.0",
                "form_identifier": "9a11b19e-077e-4715-904a-a9a2cc891837",
                "elements": [
                    {
                        "type": "input",
                        "key": "USERNAME",
                        "tags": [],
                        "version": "1.0.0",
                        "password": false,
                        "label": "Username",
                        "placeholder": "",
                        "prefill_value": "",
                        "read_only": false,
                        "validator": {
                            "min_length": 0,
                            "max_length": 20,
                            "required": true
                        }
                    },
                    {
                        "type": "input",
                        "key": "PASSWORD",
                        "tags": [],
                        "version": "1.0.0",
                        "password": true,
                        "label": "Password",
                        "placeholder": "",
                        "prefill_value": "",
                        "read_only": false,
                        "validator": {
                            "min_length": 6,
                            "required": true
                        }
                    }
                ]
            },
            "key": "eyJhbGciOiJSUzI1NiJ9.eyJtb2R1bHVzIjoiZDEwOTA3YzBkZjc4ZmI5ZDMyNmI1NzkyZGExZDg2OGRkNGViZWRiMmM1ODI4M2UxNTQ2NzFmMmZhNWY2OThiYTI3NWJjZGE0YjA4YTMwOTM4MWNiYWRlOGVmMzRhMTJkM2RhOTM3YjlmMjI4N2EyYTZjY2YxYWU4YWI3ZGRhZTM3ZWNmNzRkM2JlYWQ1OTdhNmY0ZjkwNWZiMzczNGIxY2FhOTk0ZDlhMmNmYjZiZjUyYzAwNmU2MDNmN2E1NGFlODM0NmZiY2VhZmQzODQwMjRlOWI4ZjkyOWI3ODNiMDc0MTljZGNlNGZkMmJlYTcxMzNhYjk3N2M2OWQ1NjVhNzZjMGU4MWZiMDk0NGM3N2NkMGJjYmU4ZmQ4YzY5MmQ3MDNlMDY0ZGYwNzE0OGUxMDRlOWU3ZGY1NDgxZjIwMmRkMjBiODk5ZTEwM2FlYTZiMjM1YjkyZDc4Y2I3MGMyNTNjMjE0NzcyNWVhYmVhMWU4NDZlM2YwZDgzNmYzODZiNzc3YmMwNmYyZWQzZjVmNzllMzA1YjIzM2I3OWQ1OGI3OWVkYjUxOTU5ZGJmYjk4MjM0YmE1MDE3MWVjM2ZlZWMxOTU4Mjc2NDg1NzEyZjI3MDk1ZGNlZDQ4NDVlYjgyMzg4YWVlMmFjOWRlMDc2YzNiMjE1YzY3OTNjMDNmODkiLCJleHBvbmVudCI6IjEwMDAxIn0.zEfK3O9geI1h4l2SaxxUnbfR3pKy0a5CUs3Bfwxgmd56JCOIIMX-l7KhefELqAALekUwFXT0RnMFWmD4DY99p1gT3ETNeZEe_Spv1ednlrVpaMOi68-FT91l3tyoo-XzycCNeTJ1aGqrttZbuMzAOqLfMnwqd0PszzN7pPEDbwEoatWpX5UpTpYQNNDigZHZOHERqaYEP2Kq0YyZUBYxqPPr_Tvm6qGB4iRB6UG3DxIdCoHV_M3fmuHCP62qI9mHArLP96CC4PcAlGnqLUkRQyWgw5Kdfqj0j5LSNq4CHYlva_KcQAFjGYyBd0GwRUrFZPE6VUWda9Lt4dk0AVY1Pw",
            "context": "authentication"
        }
    }
}

Responding to the Auth API

When the Auth API requires a information from the consumer, e.g. through a form, a redirect or the bank_search, the response needs to be sent to the Auth API as well. The POST request needs to be made towards the URL provided in the data.next property of the response of the previous GET request towards the Auth API.

POST <data.next> HTTP/1.1
Host: <Host>

curl -X "POST" "<data.next>"

The payload of this POST request depends on the type of the response in the previous call. The response to all of these requests is the same as the one provided in the above section "Fetching the current State from the Auth API". Don't forget to add the keys object described in White label Integration.

Responding to bank_search

If a bank_search is submitted the request payload is expected to have the following JSON structure:

{
    "bank_code": String,
    "country_code": String
}

Responding to form

If a form is submitted the request payload is expected to have the following JSON structure:

{
    "ct": String,
    "iv": String,
    "ek": String
}

It holds the encrypted data of the form response. This additional encryption only has to be done when responding to a form.

The payload of the encrypted data has to be structured as follows:

{
    "form_identifier": String,
    "data": Array<{
        "key": String,
        "value": any
    }>
}

The root element has to have two properties.

These Examples depict several forms and the structure of their corresponding responses.

Responding to redirect

If a redirect is submitted the request payload is expected to have the following JSON structure:

{
    "return_url": URL,
    "redirect_id": String
}

Retrieving Information about a Redirect

Start redirect from an id

If you want to retrieve information for a redirect from the redirect_id you can use the start endpoint.

POST /xs2a/v1/redirect/start HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Token <token>
Host: <Host>

  <payload>

curl -X "POST" "<Host>/xs2a/v1/redirect/start" \
         -H "Content-Type: application/json;charset=utf-8" \
         -H "Authorization: Token <token>"  \
         -d $'<payload>'

where the <payload> is defined as

{
     "redirect_id": String
}

The endpoint will respond with a 200 OK if a corresponding redirect is found:

{
    "redirect_url": String,
    "auth_url": String,
}

If no corresponding redirect is found the endpoint will return 404 NOT FOUND.

Resume from an url

If a consumer returns from a redirect there are certain scenarios for which it might be difficult or even impossible to identify the corresponding flow from which the redirect was started. In such cases the resume endpoint could be used to re-identify the corresponding flow from an url.

POST /xs2a/v1/redirect/resume HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Token <token>
Host: <Host>

  <payload>

curl -X "POST" "<Host>/xs2a/v1/redirect/resume" \
         -H "Content-Type: application/json;charset=utf-8" \
         -H "Authorization: Token <token>"  \
         -d $'<payload>'

where the <payload> is defined as

{
     "return_url": String
}

The endpoint will respond with a 200 OK if a corresponding flow is found:

{
    "auth_url": String,
    "redirect_id": String
}

If no corresponding flow is found the endpoint will return 404 NOT FOUND.