FLOWS.mdx

Flows

The following diagrams describe all the user flows available in Internet Identity (II).

Ths diagram use some conventions:

• A diamond {} node means that this can be an entry point for a user.
• A question mark ? in the beginning of the screen's name means that the screen depends on the user's or II's state.
• The name of the screens are the same names used in the showcase.

The following flows only take into account the II screens. Not the Webauthn flows. Those depend on the OS, password manager and device of the user.

Registration

There are three different entry points:

• dapp. The user starts in a dapp like Open Chat and decides to register with Internet Identity.
• authorizePick. The user visits the main II page directly.
  • This screen is shown if the user already has identities used in that browser.
• authorizeNew. The user visits the main II page directly.
  • This screen is shown if the user has NO identities in that browser.

These are all the possible paths that a user might take:

flowchart TD
%% Nodes
    A{dapp}
    B{authorizePick}
    C{authorizeNew}
    G(? promptCatpcha)
    H(displayUserNumber)
    I(authorizeUseExisting)


%% Edge connections between nodes
    A --> B --> I --> A
    A --> C --> G --> H --> A
    B --> I
    C --> H
    I --> A

Loading

Login

The user wants to log in to a dapp (like Open Chat) or log in directly to II.

There are the same entry points as in the registration flows:

• dapp. The user starts in a dapp like Open Chat and decides to log in with Internet Identity.
• authorizePick. The user visits the main II page directly.
  • This screen is shown if the user already has identities used in that browser.
• authorizeNew. The user visits the main II page directly.
  • This screen is shown if the user has NO identities in that browser.

There are four main groups of flows:

• Recovery flow. The flow below promptRecovery.
• User another device. The flow below promptUserNumber which comes from clicking "Continue with another device" in authorizeUseExisting.
• Warning screens. There are two possible warning screens registerCurrentDeviceCurrentOrigin and addDeviceWarningOnePasskey.
• Normal flow. Using the authorizePick, and authorizeUseExisting to authenticate.

These are all the posible paths that a user might take when logging in:

flowchart TD
%% Nodes
    A{dapp}
    B{authorizePick}
    C{authorizeNew}
    D(? registerCurrentDeviceCurrentOrigin)
    E(? addDeviceWarningOnepasskey)
    F(pollForTentativeDevicePage)
    I(authorizeUseExisting)
    J(promptUserNumber)
    K(promptDeviceTrusted)
    L(deviceRegistrationDisabledInfo)
    M(showVerificationCode)
    N(addDeviceSuccess)
    O(promptRecovery)
    P(recoverWithPhrase)
    Q(promptDeviceAlias)
    R(recoverWithDevice)
    S(forgotNumber)


%% Edge connections between nodes
    A --> B --> D --> E --> A
    A --> C --> I --> A
    B --> I
    B --> A
    B --> E
    D --> A
    E --> F --> A
    I --> D
    I --> E
    I --> J --> K --> L --> M --> N --> A
    I --> O --> P --> Q --> A
    O --> R --> Q
    O --> S

Loading

Manage Identity

This flows are triggered after the user arrives to the displayManage page and performs different actions.

This is not an exhaustive list of actions that the user might take in the manage page. There are some actions that do not trigger other screens and therefore are not included in here.

The actions listed here are:

• promptDeviceAlias: Rename a passkey.
• addPhrase: Create a seed phrase.
• resetPhraseInfo: Reset seed phrase.
• dappsExplorer: Visit list of dapps that integrate with II.
• protectDeviceInfo: Lock seed phrase.
• unprotectDeviceInfo: Unlock seed phrase.
• pollForTentativeDevicePage: Add new passkey.

The entry point is the displayManage page.

The following are all the possible flows from the manage page:

flowchart TD
%% Nodes
    A{Manage}
    B(promptDeviceAlias)
    C(resetPhraseInfo)
    D(?recoverWithPhrase)
    E(displaySeedPhrase)
    O(confirmSeedPhrase)
    F(addPhrase)
    G(dappsExplorer)
    H(protectDeviceInfo)
    I(recoverWithPhrase)
    J(unprotectDeviceInfo)
    K(pollForTentativeDevicePage)
    L(addDeviceSuccess)
    M(verifytentativeDevice)
    N(addeviceSuccessStepper)

%% Edge connections between nodes
    A --> B
    A --> C --> D --> E --> O
    A --> F --> E
    A --> H --> I
    A --> J --> I
    A --> K --> L
    K --> M --> N
    A --> G

Loading

Add Device

Adding a device needs two flows:

• Authenticated flow. Which will allow adding the device to an identity. Done with the device already added to the identity.
• Adding device flow. The flow the new device needs to complete to be added.

The user can start with either flow.

If the user starts "Adding device flow" by selecting "Continue with another device" in authorizeUseExisting. Then, the user needs to log in with the authenticated device and go to pollForTentativeDevicePage from the manage page.

If the user starts from the manage page, then the user needs to perform the following flows in the new device:

flowchart TD
%% Nodes
    A(promptDeviceTrusted)
    B(showVerificationCode)
    C(addDeviceSuccessStepper)
    D{Manage}

%% Edge connections between nodes
    A --> B --> C --> D

Loading

When the user visits the URL, it sees the screen promptDeviceTrusted, which is the entry point of the flow.

Verifiable Credentials

There is one final flow possible in II: Sharing verifiable credentials with a relying party from an issuer.

This flow is triggered by a dapp when requests to present a credential from the user.

flowchart TD
%% Nodes
    A{dapp}
    B(allowCredentials)
    C(?abortedCredentialsExternalError)

%% Edge connections between nodes
    A --> B --> C --> A
    B --> A

Loading