Introduction

An overview of the HyperID service and its integration.

HyperID is an identity provider, a trusted service that authenticates and verifies a user's identity.

With the user's consent, it grants access to the user's information to third-party applications such as web services and decentralized applications (dApps). This information is provided in the form of JSON Web Tokens, containing user attributes such as userID, email address, Web3 wallet addresses, and more.

Additional information can be requested using the obtained token. HyperID operates in accordance with the OpenID Connect 1.01 (OAuth 2.0) protocol.

In addition to standard account management logic using email and password, HyperID offers users a wide range of external Web Identity Providers for authentication, including Google, Microsoft, Discord, Twitter, and Telegram.

HyperID also provides the ability to verify one's identity by connecting to a Web3 wallet through external providers (such as MetaMask, WalletConnect, and Phantom) that connect to a Web3 wallet and validate the authentication request with a digital signature.

HyperID's authentication window

Single Sign-on Session

As an identity provider, HyperID also provides users with a Single Sign-On (SSO) session mechanism within the user's web context. This allows users, once logged in to HyperID within a specific web context, to access multiple services within that browser context without the need for additional authentication. This significantly enhances user experience.

In order to improve security and prevent potential vulnerabilities during extended sessions, a service can request user confirmation for actions within the service by using a custom request within a HyperID Multi-Factor Authentication (MFA) application. This application utilizes biometrics to confirm actions in a simple and easy-to-use manner.

A MFA request to log in to the service with a live SSO session

Integration

Services, dApps and other applications that integrate with HyperID can interact with the service by initiating a specific User Flow with a required mode in a separate window/iFrame and making REST API requests based on tokens received from HyperID for that user without the user interaction.

User Flow

It refers to a set of series of user steps on HyperID web pages that vary depending on the mode selected. Essentially, it is an implementation of the OAuth/OpenID Connect protocol extended to include a Mode option.

All modes within HyperID utilize the same authentication user flow. This User Flow always verifies the Single Sign-On (SSO) session, and if one is not found, it guides the user through the authentication process.

Subsequently, HyperID directs the authenticated user through the steps corresponding to the selected mode. Importantly, services are not required to check for the presence of an SSO session - instead, they can directly initiate the necessary mode. The User Flow can be initiated by services using either GET or POST requests.

Following is the first mode to guide the user through the universal WEB / WEB3 Authentication within the current WEB context. Its primary objectives are to establish a Single Sign-On (SSO) session, obtain user consent to access their email for initiator, and provide refresh and access tokens to the service.

URI

https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/auth
    ?response_type=code
    &client_id=your_app_client_id
    &redirect_uri=https%3A%2F%2Fyourapp.com%2Fcb
    &scope=openid+email
    &flow_mode=0

HTTP Request

GET /auth/realms/HyperID/protocol/openid-connect/auth
?response_type=code
&client_id=your_app_client_id
&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcb
&scope=openid%20email
&flow_mode=0 HTTP/1.1
Host: login.hypersecureid.com  

User Flow parameters

This request can include a specific set of mandatory parameters, as well as optional ones:

• flow_mode: Specifies which mode the user needs to go through. Frequently used modes: Authentication, KYC, connecting a wallet, request web3 transactions, etc. Details are described in the corresponding topics.

• response_type=code: Now, it has to be only ‘code’ type (Authorization Code Flow), all others are prohibited. But in general, Response Type specifies a value that determines the authorization processing flow to be used, including what parameters are returned from the used endpoints.

• client_id=your_app_client_id: It’s one of the registered developer’s ID in the HyperID dashboard. Typically, it identifies a specific dApp, web service or native application owned by the developer. However, it's worth noting that multiple applications developed by the same developer can share the same 'client_id'. For instructions on how to register a 'client_id' for your project, please refer to the provided reference.
• redirect_uri: Redirection URI to which the response will be sent. It is crucial that this URI precisely matches one of the pre-registered Redirection URI values for the Client in the HyperID development dashboard (see reference). HyperID may set one or several result parameters, depending on the chosen 'flow_mode'. However, there is one mandatory parameter and an optional one:

  • code: A one-time number used to request HyperID for the user tokens (refresh and access tokens) for the current user session from the service backend. The permissions granted to these tokens will be configured based on the consents requested in the flow's 'scope'.

  • [optional] state: An opaque value employed to preserve state information between the initial request and the callback. Please note that it is an optional parameter. Further details can be found below.

  • [optional] Other parameters depend on the 'flow_mode', please check the needed topic.

• scope: Defines the type of user resources that the service initiator intends to access. If the user has not granted prior consent to allow this service access to their data, HyperID will prompt the user to do so during the authentication process. It's important to note that if requests are made with a token without the necessary user consent, HyperID will respond with an access error. Frequently used scopes (the required scope is indicated in the description of each specific request):

  • 'email': This is the default value and can be omitted. It grants access to the user's email.

  • 'kyc-verification': This scope provides access to information related to the user's KYC (Know Your Customer) verification.

  • 'user-data-get': With this scope, access is granted to user information, a list of web3 wallet addresses connected to this service by the user, and access to the key-value database installed by this service or other services on the user.

  • 'user-data-set': This scope allows the setting of data into the key-value database of a specific user, either for the service itself or for other services.

• [Optional] state: An opaque value employed to preserve state information between the request and the callback. HyperID automatically sets this parameter with its value in the redirectURI request. Typically, dApps and native applications utilize this parameter to identify a result and match it with the internal state.

User Flow general steps

Since the User Flow is based on the OpenID Connect protocol, requests for all modes follow the next sequence:

1. The service initiates the User Flow in a window that aligns with its business logic. This window can take various forms, such as a pop-up window within the service, a visible or invisible frame, a built-in web view within a native application, or even an external browser. The initiator must specify all the necessary parameters, including 'flow_mode', as well as any optional parameters that depend on the chosen 'flow_mode'.

2. If there is no Single Sign-On (SSO) session, HyperID guides the user through the authentication process. After verifying the session, it proceeds to guide the user through the steps of the specified User Flow Mode.

3. Upon completing all the steps of a particular mode, HyperID sends the result to the initiator through the redirectURL, including the 'code' parameter. This code is short-lived and is meant for a one-time exchange for access and refresh tokens.

   HTTP/1.1 302 Found Location: https%3A%2F%2Fyourapp.com%2Fcb:8081
   ?locale=en
   &session_state=e5ec6776-bd5c-4d02-bb75-ce1c7f5a78f5
   &code=0e8fdf3e-5240-42a8-9ad7-9567418bf56d
           .e5ec6776-bd5c-4d02-bb75-ce1c7f5a78f5
           .e1427403-56a3-402d-85a8-40c178a4c358
           .0

4. The initiator subsequently processes the redirectURL request and makes a request to HyperID to exchange provided code for tokens (see reference).

   • It's important to note that since each type of User Flow Mode updates the user's tokens, the service initiator is obligated to update its tokens using the provided code. Failure to do so may result in the old tokens becoming invalid in most cases.

   • Once you have the access token (which is in the from of a JSON Web Token - JWT), you will need to parse it to retrieve the specific user information you're interested in, such as the web3 wallet address.

REST API

This RESTful API allows you to send requests to Hyper ID to retrieve or update service data for a specific user.

• Every request must include client authentication information, consisting of the 'client_id', and either the 'client_secret' or 'client_assertion' parameters (see reference). This authentication process is a prerequisite before any actions can be executed within the system.

• Each request necessitates the inclusion of a token obtained as a result of a User Flow Mode request.

• The service must have set the required 'scope' to obtain the user's consent during token acquisition via User Flow Mode. If the consent required for the REST API request is not granted for the specified token, HyperID will reject the REST API request

• There are two endpoints for REST API:

  • login.hypersecureid.com - this endpoint is used for tasks such as retrieving user information, reissuing tokens, validating tokens, logging out the user's Single Sign-On (SSO) session for all services in the web context, and revoking a service from the current SSO session.

  • api.hypersecureid.com - this endpoint is utilized for various functions including requesting user 2FA, custom MFA requests, obtaining KYC information, retrieving user social account information, accessing the user's web3 wallet addresses, and more.

Sandbox

For developers' convenience, the service offers a sandbox mode. While it may have lower performance, this mode enables developers to conduct research on the service, integrate their applications, and thoroughly test the integration before transitioning to the production environment.

To work with the sandbox environment, it needs to create a separate 'client_id' and 'client_secret' in the Hyper ID dashboard.

In the sandbox environment, you can utilize the following endpoints:

• https://login-sandbox.hypersecureid.com

• https://api-sandbox.hypersecureid.com