Detailed flow

An oboarding session is triggered by a HTTP POST to the /sessions endpoint. It has to include three elements:

• client_id: identifies your tenant application

• client_app_key: authorizes the call (safe to be used from a client app)

• skill: which skill you're starting the onboarding session for. This is taken from the skills catalog published and updated on our docs.

{
  "client_id": "{{client_id}}",
  "client_app_key": "{{client_app_key}}",
  "skill": "xyz_aisp_sbx_#1.0"
}

Following a successfull call, you will receive a message including:

• a session_id: identifies the newly created session. You will use this to submit subsequent steps.

• a nonce: a temporary token safe to be used from a client app. You will use this to submit data in the next iteration - that would be step #1 into your session. Currently the nonce expires in 30 minutes.

• a status: an informative message

{
  "nonce": "F3YXJlCjAwMT...ToxNToxNS41OTE5Nz",
  "session_id": "7489fe74-...-cd5e05c0fc4b",
  "status": "SESSION_CREATED"
}

Now that the session is created, you can start submitting data specific to each skill. At each iteration you specify the step and provide the nonce retrieved from the previous one. In a multi-step session, at each step submission, the response message will include a step_id and the nonce for the next step.

Use the /sessions/{session_id}/steps endpoint to submit data for a specific step.

{
  "client_id": "{{client_id}}",
  "nonce": "{{nonce}}",
  "skill": "xyz_sbx_#3.0",
  "step": "product_form",
  "data": {
    "value": "100000",
    "currency": "EUR",
    "period": "12"
  }
}

At certain steps, a skill might require specific uploads. An example would be an onboarding session for a credit card product. The KYC (know your customer) flow asks for personal data, ID upload and photo/selfies.

Use the /steps/{step_id}/upload endpoint to submit uploads for a specific step.

In the above diagram please notice the moments where nonce for each step and the temp_token are generated. The nonce to be used for any API call related to step #1 is generated when the session is initialized. The nonce to be used for any API call related to step #2 is generated when step #1 data is submitted.

The temp_token is generated when you submit data with the last step - in the example above, the session has two steps, hence it's generated with Step #2. This marks the end of a successful user session: user consent has been given or the product onboarding was done without any issue.

This is an important point in this flow, as you need to make the switch to the server-side. The switch is made by sending the temp_token to your backend server. This is where you call the /token endpoint to exchange it for an access_token along with the credentials_id that points to the newly created object/s.

The call to /token is authenticated by using the client_id and client_secret. The access_token plus the credentials_id need to be stored by your backend along with the end-user data.