Adding Passwordless Login to your In-House / Custom Application

Adding secure, passwordles login to your custom application is relatively easy with BlokSec - you will need to use two straightforward RESTful APIs - POST /registration and POST /auth

Pre-requisites

In order to use the required APIs, you will need an application created in the administrative console from which you can get the Application ID (required for the x-application-id header) and Application Secret (required for the x-application-secret header) required to authorize the API call. Please see Custom OIDC for instructions on how to create this application in the BlokSec Admin Console.

Registration

Before users can use BlokSec for secure passwordless authentication, they must be registered. Registration can be done with a bulk-load utility, via SCIM API (docs coming soon), or in real-time by leveraging the POST /registration API.

Registrations are sent to users via email; the email contains a link to the registration request which must be retrieved by their authenticator app (e.g., the BlokSec yuID Authenticator App, or your custom authenticator application) to complete the linking of their account with their authenticator instance. How and when you register users is up to you, but it is important only to ensure that registrations are only sent to trusted, verified email addresses. We do recommend including registration as part of the new user onboarding process for your application while the user's identity is being established.

To register a user with BlokSec, call the POST /registration API:

For help on using the API including the schema, expected request values, and expected response, please see the OpenAPI documentation at the link above.

If you would like to check the status of a registration request, you can look it up with the GET /registration/{registrationId} API with the registration ID returned by the POST /registration API:

Authentication / Authorization

Once a user has been registered, they're ready to perform MFA / 2FA authentication during login. You can also use the BlokSec service to perform step-up authorization during important transactions. To send an auth* request (auth = authentication or authorization) you invoke the POST /auth API:

Note that this is a synchronous API so your call will block while waiting for the user's response. We suggesting showing a user-friendly message along with a spinner to provide the user with feedback that a response is pending their action. The following diagram illustrates the call sequence:

sequenceDiagram
    participant Custom App
    participant BlokSec
    participant User
    Custom App->>+BlokSec: POST /auth 'username'
    Note right of Custom App: Synchronous API
    BlokSec-->>User: [Authentication Challenge]
    User-->>BlokSec: [Challenge Response]
    BlokSec->>-Custom App: [success / failure]]

The response from the API will have the following format:

{
  "requestId": "622b95833bab53f6bba946d0",
  "status": "accepted"
}