Concepts

The QuickCheckin/QuickLogin API is the Yang to the Issuance API’s Yin. It allows a verifier to challenge a wallet holder to cryptographically prove that they are in possession of a valid credential by some set of criteria. What criteria? Read on to find out.

Terms:

1. QuickCheckin: This is for in person events where you may want to integrate a kiosk to accept Heirloom credentials via QR scan
2. QuickLogin: This is for online authentication use cases (e.g. logging into a website or token-gating an app)

Flow

The general flow of presenting a credential for a QuickLogin or QuickCheckin is as follows:

sequenceDiagram
    participant FE as 3rd Party Frontend
    participant HeirloomBE as Heirloom Backend

    autonumber
    Note over FE: "QuickLogin" button clicked
    FE->>HeirloomBE: POST /auth/sessions/challenges
    HeirloomBE->>FE: Return loginChallenge
    FE-->>FE: Open WebSocket
    activate FE
    Note over FE: Render QR code
    create participant Device as Mobile Device
    FE-->Device: Mobile Device scans QR code
    Note over Device: Construct VP
    Device->>HeirloomBE: POST /auth/verify-presentation
    Note over HeirloomBE: Validate Credentials
    HeirloomBE-->>FE: Send payload to Frontend<br>(WebSocket)
    deactivate FE
    destroy Device
    HeirloomBE->>Device: 201 Response
    FE->>FE: Handle payload

1. Client application requests a challenge from the Heirloom API using their API key
2. Heirloom API returns a payload containing a loginChallenge (See details below)
3. Client:
   1. Opens up a WebSocket to listen for success/failure of the Verifiable Presentation (VP)
   2. Uses the loginChallenge to render a QR to display to the user
4. After a Mobile Device scans the QR code, the wallet finds a credential which satisfies the challenge and the user approves a signed VP
5. The wallet sends the VP to the Heirloom API
6. Heirloom API verifies the presentation is valid for the given challenge & sends access token/payload data back to the client over WebSocket
7. Heirloom API sends response back to the Mobile Device
8. Client application receives data and decides what to do with it

Challenge

A challenge accomplishes two things: it provides an interface for specifying what credentials are accepted to satisfy the challenge, and it ensures protection against replayability of signatures. Encoded in the challenge is a credentialQuery which provides a (relatively) light-weight interface for specifying what credentials will satisfy the challenge, and a randomly generated value that is required to be included in a presentation. This is all wrapped up in a JWT that is signed by Heirloom’s servers to ensure that the challenge was authentically generated by Heirloom’s API.

Locks

Locks are a higher level abstraction that encapsulates the challenge and contains various settings that include the credentialQuery, the amount of time that a challenge is valid for, what CORS domains are allowed to use the lock, the API keys that you will need to embed in your application to make use of the lock, etc.