Workflow

  • The end-user is a visitor on the partner’s website website: he only interacts with the partner’s website.

  • The website displays a form to the user, along with a ocapi.js link that will render the challenge

  • The ocapi service is a REST API that both the user's browser and your website will use to get challenges and validate them.

sequenceDiagram user->>website: visit page website->>user: form + ocapi.js user->>ocapi: ask for challenge ocapi->>user: challenge X is provided user->>user: fill in form + ocapi user->>ocapi: is challenge X valid ? ocapi->>user: OK/KO user->>website: submit form + challenge X website->>ocapi: is challenge X valid ? ocapi->>website: OK/KO website->>user: custom response based on ocapi

Steps

  1. The end-user visits the partner’s website with his browser: he gets an HTML page and our ocapi.js payload, alongside some public credentials to identify which challenge will be later served.

  2. His browser renders the form, and the ocapi.js script makes an HTTP GET query on the Ocapi instance to get a new challenge.

  3. The challenge is created, sent as a JSON payload to the browser.

  4. The challenge is then properly rendered by ocapi.js on the end-user browser.

  5. The end-user can start to fill the partner’s form as soon as it’s displayed, but he must fill in the Ocapi form to validate the form.

  6. Once the user click on the Ocapi validation button, an HTTP POST request is triggered to check if the user’s answer is valid.

  7. If the answer is invalid, a new challenge is automatically created, and the user must retry.

  8. If the answer is valid, the user can submit the full form.

  9. The partner’s website must now check that the challenge is indeed valid, and makes an authenticated GET query on the Ocapi instance

  10. The Ocapi instance sends back a simple state message in a JSON payload.

  11. The partner’s website can then proceed the form (if the state is valid), or reject it entirely.

HTTP Requests

All HTTP requests between the end-user browser and the ocapi instance do not need any form of authentication: a user can only:

  • create a new challenge

  • update this challenge with his answer

The partner’s website can authenticate itself using a JSON web token with an HMAC signature (using a provided secret key), so it can:

  • check a challenge provided by its user is valid.

You can view the OpenApi specification here.