NAV Navbar
shell javascript

Introduction

Endpass Connect makes it easy for developers to verify a user's identity.

The Endpass platform contains two main components:

All Endpass APIs are built on oAuth2 standards, and will be easy to use for developers who are familiar with building oAuth clients.

Quick Start

A quick start example of using the Endpass Connect library in your web app.

Example App

1. Register Application

Visit the Endpass dashboard and create a new application.

Save your Client ID for use later in this tutorial.

More about application registration

2. Add Endpass Connect Library

Run one of these commands to install the Endpass Connect library

# If using npm
npm i --save @endpass/connect

# If using yarn
yarn add @endpass/connect

Import Endpass connect as html script tag

<script src="https://unpkg.com/@endpass/[email protected]" type="text/javascript"></script>
<script src="https://unpkg.com/@endpass/[email protected]/oauth.min.js" type="text/javascript"></script>

Add the library to your application using the npm or script tag method.

More about installing the Endpass Connect library

3. Request User Information

// If you are using modules or npm
import EndpassConnect from '@endpass/connect';
import EndpassOauthPlugin from '@endpass/connect/oauth';

// Insert your client ID here
const YOUR_CLIENT_ID = '';

// Scopes determine permissions requested from the user
const scopes = [
  'user:email:read',
  'user:phone:read',
];

// Initialize a new client instance
const connect = new EndpassConnect({
  oauthClientId: YOUR_CLIENT_ID,
  // The Oauth plugin is required to access user data
  plugins: [EndpassOauthPlugin],
  scopes,
});

// Call the client's request method with any API endpoint
connect.request('/user').then(console.log);

Initialize a new instance of the client with the scopes required for your application.

Call the connect.request method to request information from the user. This method will open a window allowing the user to log in and grant permissions based on your application.

For example, connect.request('/user') will return a promise with basic user information.

List of scopes

Concepts

Identity Verification Flow

For a typical application, the flow for identifying and verifying a new user will be as follows:

  1. The Endpass Connect library is triggered by a Javascript method call or the user's click on a "Login With Endpass" button.
  2. The user is prompted to log in to their Endpass account in a new window. If the user does not have an Endpass account, they will be able to create one without leaving your application.
  3. The user is shown a permissions dialog to approve access to the scopes requested by your application.
  4. The user is prompted to upload any additional documents needed to verify additional scopes.
  5. The user's documents are instantly verified by the Endpass backend.
  6. The Endpass Connect Javascript library returns a Promise with the data requested.
  7. Your server-side application retrieves additional user information, like document data and verification status.

Scopes

Scopes represent the information you are requesting from a user. Scopes must be explicitly defined when the Endpass Connect library is initialized.

When the user clicks the "Login With Endpass" button, a permissions dialog with the requested scopes will be shown to the user.

Try to request the minimal number of scopes required for your application. Users are more likely to agree to a smaller set of permissions.

List of Scopes

Scope Description
user:email:read Get the user's email address
user:address:read Get all of a user's physical addresses with verification status
user:phone:read Get all of the user's phone numbers with verification status
documents:status:read Get the verification status of all of the user's identity documents
documents:data:read Get all of the data, like name, number, and expiration date from all of the user's identity documents
documents:image:read Get the actual identity document images submitted by the user
wallet:address:read Get the user's primary cryptocurrency address
wallet:accounts:read Get all cryptocurrency addresses in the user's wallet

Documents

Documents represent the identity documents submitted by the user. After a document is submitted, it is automatically verified by Endpass AI technology. You do not need to verify that a document is valid if it has the "Verified" status.

Authentication

Application Registration

To integrate Endpass auth into your application, you first need to register it in your Endpass dashboard.

Required data:

Key Description
Domain The domain in which your application will be hosted
RedirectUrls List of available redirect URLs after successful authorization

After registration, you will receive the application client ID and client secret for future use.

Access Tokens

After registering an application, you will receive a client id and client secret.

The client ID and client secret can be used with your preferred oAuth2 client library to acquire an access token for a particular user of your application.

Endpass Connect client

Installation (npm)

The Javascript client library can be installed with a package manager like npm, or directly included in an HTML file from a script tag.

Install the library via npm or yarn.

Run one of these commands to install the Endpass Connect library

# If using npm
npm i --save @endpass/connect

# If using yarn
yarn add @endpass/connect

Installation (CDN)

If you are not using a build system like Webpack in your project, you can load Endpass Connect from CDN with a script tag.

Import Endpass connect as html script tag

<script src="https://unpkg.com/@endpass/[email protected]" type="text/javascript"></script>
<script src="https://unpkg.com/@endpass/[email protected]/oauth.min.js" type="text/javascript"></script>

Loading a specific version

Loading the latest library version is recommended for most use cases. For advanced users, it is possible to specify a specific version to load in the script source.

https://unpkg.com/@endpass/[email protected]

The list of versions can be seen on npm.

Alternate CDN

If there are issues with the primary unpkg CDN, the jsdelivr CDN can also be used.

Latest version:

https://cdn.jsdelivr.net/npm/@endpass/[email protected]

Specify a version:

https://cdn.jsdelivr.net/npm/@endpass/[email protected]

Content Security Policy

If you want to use Endpass Connect with CSP rules, just copy/paste this code into the <head> tag of your html page.

Paste this code into your head tag if you are getting CSP errors

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: *.endpass.com; script-src 'self' data: 'unsafe-inline' 'unsafe-eval' *.endpass.com unpkg.com; object-src 'self' *.endpass.com; style-src 'self' data: 'unsafe-inline' *.endpass.com; img-src 'self' *.endpass.com; media-src 'self' *.endpass.com; frame-src 'self' *.endpass.com; font-src 'self' *.endpass.com; connect-src 'self' *.endpass.com"/>
Name Description
OAuth For getting private user information from Server API

Usage

Create a new instance of the connect client with your application's Client ID and custom configuration options.

// Insert your client ID here
const YOUR_CLIENT_ID = '';

// Initialize Connect with clientId from vault and plugin composition
const connect = new EndpassConnect({
  oauthClientId: YOUR_CLIENT_ID,
  plugins: [EndpassOauthPlugin],
  // Your can pass scopes to the instance or to each request separatly
  scopes: ['user:email:read'],
  // Choose popup separate window or modal iframe (default modal)
  oauthPopup: false,
});

// or separate plugin instance
const connect = new EndpassOauthPlugin({
  oauthClientId: YOUR_CLIENT_ID,
});
const scopes = [
  'user:email:read',
  'user:phone:read',
];

const requestParams = {
  url: 'https://api.endpass.com/v1/user',
  method: 'GET',
  // Also you can pass scopes to the instance
  scopes,
}

// async / await
(async () => {
  // Fetch required data
  const userInfo = await connect.request(requestParams);

  console.log(userInfo);
})();

User info response

{
  "id": "0d8c5fa3-c8a5-4c5f-8435-f35aef353f30",
  "email": "[email protected]",
  "phones": [
    {
      "id": "c4d4ef1c-0d73-4a6f-aad9-7600a8fc79b8",
      "createdAt": 1557220652,
      "status": "Verified",
      "country": "7",
      "number": "7771112233"
    }
  ]
}

The connect client wraps a standard oAuth2 REST client instance. You can pass parameters to the request method to access any server API endpoints.

OAuth plugin

// Insert your client ID here
const YOUR_CLIENT_ID = '';

// Initialize Connect with clientId from vault and plugin composition
const connect = new EndpassConnect({
  oauthClientId: YOUR_CLIENT_ID,
  plugins: [EndpassOauthPlugin],
  // Your can pass scopes to the instance or to each request separatly
  scopes: ['user:email:read'],
  // Choose popup separate window or modal iframe (default modal)
  oauthPopup: false,
});

// or separate plugin instance
const connect = new EndpassOauthPlugin({
  oauthClientId: YOUR_CLIENT_ID,
});
const scopes = [
  'user:email:read',
  'user:phone:read',
];

const requestParams = {
  url: 'https://api.endpass.com/v1/user',
  method: 'GET',
  // Also you can pass scopes to the instance
  scopes,
}

// async / await
(async () => {
  // Fetch required data
  const userInfo = await connect.request(requestParams);

  console.log(userInfo);
})();

User info response

{
  "id": "0d8c5fa3-c8a5-4c5f-8435-f35aef353f30",
  "email": "[email protected]",
  "phones": [
    {
      "id": "c4d4ef1c-0d73-4a6f-aad9-7600a8fc79b8",
      "createdAt": 1557220652,
      "status": "Verified",
      "country": "7",
      "number": "7771112233"
    }
  ]
}

Connect provides Oauth authorization flow which can be used for user authentication and private API calls.

To implement it you first need to register you application at Endpass-vault and receive your clientId.

Create instance of class and use it in your application. You can know about options and methods in the instance methods section.

Demo

Options

The following options can be passed when initializing the OAuth plugin.

bold parameters are required.

Name Type Description
oauthClientId string The client ID of your application.
scopes string array The list of scopes to request from the user
oauthPopup bool If true, open permissions dialog in a new popup window. If false, open it in a modal iframe. Default: false.

Methods

Method Params Returns Description
request { url: string, method: string, headers: object, params: object, data: string object, scopes?: array<string> } Promise Makes and http request with access token. You can pass scopes to the instance constructor or to each request separately
logoutFromOauth Promise Logout the currently authenticated oAuth user

Login button plugin

Run one of these commands to install the Endpass Connect library

# If using npm
npm i --save @endpass/connect

# If using yarn
yarn add @endpass/connect
<!-- Import OAuth plugin as html script tag -->
<script src="https://unpkg.com/@endpass/[email protected]/oauth.min.js" type="text/javascript"></script>
import EndpassConnect from '@endpass/connect';
import EndpassOauthPlugin from '@endpass/connect/oauth';
// Insert your client ID here
const YOUR_CLIENT_ID = '';

// Initialize Connect with clientId from vault and plugin composition
const connect = new EndpassConnect({
  oauthClientId: YOUR_CLIENT_ID,
  plugins: [EndpassOauthPlugin],
  // Your can pass scopes to the instance or to each request separatly
  scopes: ['user:email:read'],
  // Choose popup separate window or modal iframe (default modal)
  oauthPopup: false,
});

// or separate plugin instance
const connect = new EndpassOauthPlugin({
  oauthClientId: YOUR_CLIENT_ID,
});
const scopes = [
  'user:email:read',
  'user:phone:read',
];

const requestParams = {
  url: 'https://api.endpass.com/v1/user',
  method: 'GET',
  // Also you can pass scopes to the instance
  scopes,
}

// async / await
(async () => {
  // Fetch required data
  const userInfo = await connect.request(requestParams);

  console.log(userInfo);
})();

User info response

{
  "id": "0d8c5fa3-c8a5-4c5f-8435-f35aef353f30",
  "email": "[email protected]",
  "phones": [
    {
      "id": "c4d4ef1c-0d73-4a6f-aad9-7600a8fc79b8",
      "createdAt": 1557220652,
      "status": "Verified",
      "country": "7",
      "number": "7771112233"
    }
  ]
}

Connect provides a login button for the Oauth authorization flow which can be used for user authentication.

To implement it you first need to register you application at Endpass-vault and receive your clientId.

Create instance of class and use it in your application. You can know about options and methods in the instance methods section.

Demo

Login button plugin

Method Params Returns Description
createLoginButton { element: string<Selector> or HTMLElement, onLogin: Callback<(e: Error, user: { id: string, email: sting }): any>, isLight?: boolean, label?: string } Promise Create Endpass login button instance

Login button instance

Method Returns Description
mount void Mount Endpass login button
unmount void Unmount Endpass login button

Instance methods

Methods

Method Params Returns Description
request { url: string, method: string, headers: object, params: object, data: string object, scopes?: array<string> } Promise Makes and http request with access token. You can pass scopes to the instance constructor or to each request separately
logoutFromOauth Promise Logout the currently authenticated oAuth user

Login button plugin

Method Params Returns Description
createLoginButton { element: string<Selector> or HTMLElement, onLogin: Callback<(e: Error, user: { id: string, email: sting }): any>, isLight?: boolean, label?: string } Promise Create Endpass login button instance

Errors

import ConnectError from '@endpass/connect/ConnectError';

const scopes = [
  'user:email:read',
  'user:phone:read',
];

const requestParams = {
  url: 'https://api.endpass.com/v1/user',
  method: 'GET',
  // Also you can pass scopes to the instance
  scopes,
};

// async / await
(async () => {
  try {
    // Fetch required data
    const userInfo = await connect.request(requestParams);
  } catch(e) {
    // You can match the type of error from the imported instance
    if (e.code === ConnectError.ERRORS.AUTH) {
      handleError();
    }

    // Or Connect/Plugin instance
    if (e.code === connect.ERRORS.AUTH) {
      handleError();
    }

    console.log(e);
  }
})();

Suppose an error has been thrown and can be seen in the console

{
  "message": "Some error message",
  "code": "CODE_FROM_ERRORS_SECTION",
  // ...other props from Error instance
}

Common errors

Code Description
INITIALIZE Failed to initialize Connect
NOT_DEFINED Something went wrong, but Connect doesn't know what exactly is wrong
AUTH_CANCELED_BY_USER Authentication canceled by user
AUTH Something went wrong during user authentication
AUTH_LOGOUT Something went wrong during logout

Oauth errors

Code Description
OAUTH_REQUIRE_ID Connect library requires OAuth client id, provide it to instance
OAUTH_AUTHORIZE Oauth authorization failed
OAUTH_POPUP_CLOSED Oauth frame/popup was closed and the authentication process was interrupted by user
CREATE_DOCUMENT The user doesn't have a document, Connect tried to create it, but the process failed

Plugins

Endpass Connect supports mountable plugins. By default the library includes the OAuth plugin.

Server API

User

User resource

Generic user information. By default, only public information is shared without any scopes. Verified phone numbers or email can be requested with additional scopes.

User’s public information (default)

{
  "id": "0d8c5fa3-c8a5-4c5f-8435-f35aef353f30"
}

Authenticated user with their email (user:email:read permission)

{
  ...
  "email": "[email protected]"
}

Authenticated user with their verified phone numbers (user:phone:read permission)

{
  ...
  "phones": [
    {
      "id": "c4d4ef1c-0d73-4a6f-aad9-7600a8fc79b8",
      "createdAt": 1557220652,
      "status": "Verified",
      "country": "7",
      "number": "7771112233"
    }
  ]
}
Fields Description
id (string) Resource ID
email (string) User’s email
phones (Phone) User’s verified phone numbers

Phone

Fields Description
id (string) Resource ID
createdAt (timestamp) Creation timestamp
status (string, enumerable) Verification status
country (string) Country code
number (string) Phone number

Show current user

Returns user information.

HTTP Request

GET https://api.endpass.com/v1/user

Scopes

curl "https://api.endpass.com/v1/user"
  -H "Authorization: Bearer <access_token>"

User's address

Scope: user:address:read

Request: GET https://api.endpass.com/v1/user/address

Return list of user's addresses.

Fields:

Field Description
main (boolean) Main address flag
status (string) Address status
created_at (number) Timestamp, UTC tz
apartmentNumber (string) Apartment number
streetNumber (string) Street Number
street (string) Street name
city (string) City
stateRegion (string) State region
country (string) Country
postalCode (string) PostalCode
lat (number) Latitude
lng (number) Longitude

User's personal data

Returns user's personal data fields.

Default response body

{
  "id": "be954fe3-f42a-4745-8bf0-2262faef02a4",
  "firstName": "Franz",
  "lastName": "Kafka",
  "dateOfBirth": -2729635200
}

Personal data resource

Field Description
id (string) Resource ID
firstName (string) First name
lastName (string) Last name
dateOfBirth (number) Timestamp, UTC tz

HTTP Request

GET https://api.endpass.com/v1/user/info/personal

Scopes

HTTP Status Codes

Accounts

Account resource represents all of a user’s accounts.

List of account

[
  "0x123...",
  "0x456..."
]

Account resource

{
  "address": "0x123..."
}

Account resource

Fields Description
address (string) Address hash

Show user accounts

Returns a list of user accounts that have a keystore.

HTTP Request

GET https://api.endpass.com/v1/accounts

Scopes

curl "https://api.endpass.com/v1/accounts"
  -H "Authorization: Bearer <access_token>"

Last active account

Returns user last active account.

HTTP Request

GET https://api.endpass.com/v1/accounts/active

Scopes

curl "https://api.endpass.com/v1/accounts/active"
  -H "Authorization: Bearer <access_token>"

Documents

Document resource represents a user’s document.

List of documents

[
  {
    "id": "f1f80c7a-57c7-4259-8e80-d1bb09932e82",
    "createdAt": 1543336121,
    "status": "Draft",
    "documentType": "Passport",
    "description": "Custom document description",
    "imageId": "f10c347a-59x2-4259-8e80-d1bb09932z30",
    "imageHash": "D47D9147CB585F96AB6D6B34DB0D84DD0608E0F8BC6F7604E50373347E276272",
    "mimeType": "image/jpeg",
    "backImageId": "h53c347a-59x2-4259-8e80-d1bb09932z30",
    "backImageHash": "C54D9147CB585F96AB6D6B34DB0D84DD0608E0F8BC6F7604E50373347E276272",
    "backMimeType": "image/png",
    "firstName": "Test",
    "lastName": "User",
    "number": "47313892501",
    "dateOfBirth": 1543323121,
    "dateOfIssue": 1543336122,
    "dateOfExpiry": 1543336123,
    "issuingCountry": "Country",
    "issuingAuthority": "Authority",
    "issuingPlace": "Place",
    "address": "Address"
  }
]

Document's public information (default)

{
  "id": "f1f80c7a-57c7-4259-8e80-d1bb09932e82",
  "createdAt": 1543336121
}

Document's status (documents:status:read)

{
  ...
  "status": "Draft"
}

Document's data (documents:data:read)

{
  ...
  "documentType": "Passport",
  "description": "Custom document description",
  "imageId": "f10c347a-59x2-4259-8e80-d1bb09932z30",
  "imageHash": "D47D9147CB585F96AB6D6B34DB0D84DD0608E0F8BC6F7604E50373347E276272",
  "mimeType": "image/jpeg",
  "backImageId": "h53c347a-59x2-4259-8e80-d1bb09932z30",
  "backImageHash": "C54D9147CB585F96AB6D6B34DB0D84DD0608E0F8BC6F7604E50373347E276272",
  "backMimeType": "image/png",
  "firstName": "Test",
  "lastName": "User",
  "number": "47313892501",
  "dateOfBirth": 1543323121,
  "dateOfIssue": 1543336122,
  "dateOfExpiry": 1543336123,
  "issuingCountry": "Country",
  "issuingAuthority": "Authority",
  "issuingPlace": "Place",
  "address": "Address"
}

Document resource

Fields Description
id (string) Resource ID
createdAt (timestamp) Creation timestamp
status (string, enumerable) Document current status
documentType (string, enumerable) Document type
description (string) Description
imageId (string) Front File ID
imageHash (string) Front File Hash
mimeType (string) Front File Content Type
backImageId (string) Back File ID
backImageHash (string) Back File Hash
backMimeType (string) Back File Content Type
firstName (string) First name
lastName (string) Last name
number (string) Document number
dateOfBirth (timestamp) Date of birth
dateOfIssue (timestamp) Document issue date
dateOfExpiry (timestamp) Document expiration date
issuingCountry (string) Document issuing country
issuingAuthority (string) Document issuing authority
issuingPlace (string) Document issuing place
address (string) Address

Document types

Key Description
Passport Passport
DriverLicense Driver license

Document statuses

Key Description
Draft Default status, not submitted to verification service
Recognition Submitted to verification service, waiting result
PendingReview Document queued to manual verification
NotReadable Document not readable, need update document file (image)
NotVerified Received failed result from the verification service
Verified Document verified

Show user documents

Returns all user documents.

HTTP Request

GET https://api.endpass.com/v1/documents

Scopes

curl "https://api.endpass.com/v1/documents"
  -H "Authorization: Bearer <access_token>"

Show document

Returns document by ID.

HTTP Request

GET https://api.endpass.com/v1/documents/{ID}

Scopes

curl "https://api.endpass.com/v1/documents/{ID}"
  -H "Authorization: Bearer <access_token>"

Show document's front file

Returns the document's front file content (jpeg, pdf) into binary stream.

If there is no uploaded file returns 204.

HTTP Request

GET https://api.endpass.com/v1/documents/{ID}/front/file

Scopes

curl "https://api.endpass.com/v1/documents/{ID}/front/file"
  -H "Authorization: Bearer <access_token>"

Show document's back file

Returns the document's back file content (jpeg, pdf) into binary stream.

If there is no uploaded file returns 204.

HTTP Request

GET https://api.endpass.com/v1/documents/{ID}/back/file

Scopes

curl "https://api.endpass.com/v1/documents/{ID}/back/file"
  -H "Authorization: Bearer <access_token>"

Scopes list

Scopes resource

Returns scopes granted by user for particular application.

{
  "scopes": [
    "user:address:read",
    "user:phone:read",
    "documents:status:read",
    "documents:data:read",
    "documents:image:read",
    "wallet:address:read",
    "wallet:accounts:read",
    "user:email:read"
  ]
}
Fields Description
scopes (string, array) Granted scopes list

HTTP Request

GET https://api.endpass.com/v1/scopes

curl "https://api.endpass.com/v1/scopes"
  -H "Authorization: Bearer <access_token>"

Errors

The Endpass API uses the following error codes:

Error Code Meaning
400 Bad Request -- Missing parameter or invalid request.
401 Unauthorized -- Invalid auth (invalid, expired or revoked Oauth token).
403 Forbidden -- User hasn’t authenticated necessary scope.
404 Not Found -- Resource not found.
405 Method Not Allowed -- Invalid method or route.
423 Locked -- User has been banned.
429 Too Many Requests -- Rate limit exceeded.
500 Internal Server Error -- Internal server error.