# Connect

# 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 OAuth plugin as html script tag

<!-- Import OAuth plugin as html script tag -->
<script
  src="https://unpkg.com/@endpass/connect@latest/oauth.min.js"
  type="text/javascript"
></script>
<script>
  (() => {
    // all Endpass plugins available from window
    const EndpassOauth = window.EndpassOauth;

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

    // Initialize Connect with clientId from vault
    const connect = new EndpassOauth({
      clientId: YOUR_CLIENT_ID,
      // Choose popup separate window or modal iframe (default modal)
      isPopup: false,
    });
  })();
</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/connect@0.31.0-beta

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/connect@latest

Specify a version:

https://cdn.jsdelivr.net/npm/@endpass/connect@0.31.0-beta

# 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.

Import Endpass connect OAuth plugin as html script tag

<!-- Import OAuth plugin as html script tag -->
<script
  src="https://unpkg.com/@endpass/connect@latest/oauth.min.js"
  type="text/javascript"
></script>
<script>
  (() => {
    // all Endpass plugins available from window
    const EndpassOauth = window.EndpassOauth;

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

    // Initialize Connect with clientId from vault
    const connect = new EndpassOauth({
      clientId: YOUR_CLIENT_ID,
      // Choose popup separate window or modal iframe (default modal)
      isPopup: false,
    });
  })();
</script>
// If you are using modules or npm
import EndpassOauth from '@endpass/connect/oauth';

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

// Initialize Connect with clientId from vault
const connect = new EndpassOauth({
  clientId: YOUR_CLIENT_ID,
  // Choose popup separate window or modal iframe (default modal)
  isPopup: false,
});

Usage after creation connect instance


const requestParams = {
  url: 'https://api.endpass.com/v1/user',
  method: 'GET',
}

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

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

User info response

{
  "id": "0d8c5fa3-c8a5-4c5f-8435-f35aef353f30",
  "email": "user@endpass.com",
  "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

Import Endpass connect OAuth plugin as html script tag

<!-- Import OAuth plugin as html script tag -->
<script
  src="https://unpkg.com/@endpass/connect@latest/oauth.min.js"
  type="text/javascript"
></script>
<script>
  (() => {
    // all Endpass plugins available from window
    const EndpassOauth = window.EndpassOauth;

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

    // Initialize Connect with clientId from vault
    const connect = new EndpassOauth({
      clientId: YOUR_CLIENT_ID,
      // Choose popup separate window or modal iframe (default modal)
      isPopup: false,
    });
  })();
</script>
// If you are using modules or npm
import EndpassOauth from '@endpass/connect/oauth';

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

// Initialize Connect with clientId from vault
const connect = new EndpassOauth({
  clientId: YOUR_CLIENT_ID,
  // Choose popup separate window or modal iframe (default modal)
  isPopup: false,
});

Usage after creation connect instance


const requestParams = {
  url: 'https://api.endpass.com/v1/user',
  method: 'GET',
}

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

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

User info response

{
  "id": "0d8c5fa3-c8a5-4c5f-8435-f35aef353f30",
  "email": "user@endpass.com",
  "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

If you need to combine plugins, please use Compose Plugin

# Options

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

bold parameters are required.

Name Type Description
clientId string The client ID of your application.
isPopup bool If true, open permissions dialog in a new popup window. If false, open it in a modal iframe. Default: false.

# Oauth plugin methods

request - makes and http request with access token.

Params:

{
  url: string,
  method: string,
  headers: object,
  params: object,
  data: string|object
}

Returns:

Promise


logoutFromOauth - logout the currently authenticated oAuth user

Returns:

Promise

# 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 Login Button plugin as html script tag -->
<script
  src="https://unpkg.com/@endpass/connect@latest/loginButton.min.js"
  type="text/javascript"
></script>
<script>
  // and button available from window
  const { EndpassLoginButton } = window;
</script>
// If you are using modules or npm
import EndpassLoginButton from '@endpass/connect/loginButton';

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

// Initialize Connect with clientId from vault
const connect = new EndpassLoginButton({
  clientId: YOUR_CLIENT_ID,
});

Usage after creation connect instance

const params = {
  // CSS selector or HTMLElement
  element: 'div#login',
  // Your callback
  onLogin: (err, user) => console.log(user),
  // Filled/light skin (default filled)
  isLight: false,
  // Optional custom button text (pass default for example)
  label: 'Sign in with Endpass',
};

(async () => {
  const button = await connect.createLoginButton(params);
  // And can mount/unmount this button
  button.mount();
  // ...your code
})();
// If the user clicks on the button and successfully
// continues the login process you will see in the console (callback onLogin)
{
  "id": "0d8c5fa3-c8a5-4c5f-8435-f35aef353f30",
  "email": "user@endpass.com"
}

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

If you need to combine plugins, please use Compose Plugin

# Options

The following options can be passed when initializing the Login button plugin.

bold parameters are required.

Name Type Description
clientId string The client ID of your application.

# Login button plugin methods

createLoginButton - creates Endpass login button instance

Params:

{
  element: string|HTMLElement,
  onLogin: Callback<{
    e?: Error,
    user: {
      id: string,
      email: string,
    }
  }>,
  isLight?: boolean,
  label?: string
}

Returns:

Promise

# Login button instance

mount - mount Endpass login button

Returns:

void


unmount - unmount Endpass login button

Returns:

void

# Compose 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

If you need to start multiple plugins just add following scripts in your html markup,

<script
  src="https://unpkg.com/@endpass/connect@latest/compose.min.js"
  type="text/javascript"
></script>
<script
  src="https://unpkg.com/@endpass/connect@latest/loginButton.min.js"
  type="text/javascript"
></script>
<script
  src="https://unpkg.com/@endpass/connect@latest/oauth.min.js"
  type="text/javascript"
></script>
<!-- other plugins <script/> -->
<script>
  // and plugins available from window object
  const { EndpassOauth, EndpassCompose, EndpassLoginButton } = window;
</script>

When you need multiple plugins usage, just combine them by EndpassCompose

// If you are using modules or npm
import EndpassCompose from '@endpass/connect/compose';
import EndpassLoginButton from '@endpass/connect/loginButton';
import EndpassOauth from '@endpass/connect/oauth';

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

// Initialize Connect with clientId from vault
// with passing options to each plugin
const connect = new EndpassCompose({
  clientId: YOUR_CLIENT_ID,
  isPopup: false,
  plugins: [EndpassLoginButton, EndpassOauth],
});

// After creation connect instance have the same methods as it in plugins
// like connect.request()

Connect provides a special compose plugin for combine different plugins into one instance

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.

# Oauth plugin methods

request - makes and http request with access token.

Params:

{
  url: string,
  method: string,
  headers: object,
  params: object,
  data: string|object
}

Returns:

Promise


logoutFromOauth - logout the currently authenticated oAuth user

Returns:

Promise

# Login button plugin methods

createLoginButton - creates Endpass login button instance

Params:

{
  element: string|HTMLElement,
  onLogin: Callback<{
    e?: Error,
    user: {
      id: string,
      email: string,
    }
  }>,
  isLight?: boolean,
  label?: string
}

Returns:

Promise

# Instance methods

# Oauth plugin methods

request - makes and http request with access token.

Params:

{
  url: string,
  method: string,
  headers: object,
  params: object,
  data: string|object
}

Returns:

Promise


logoutFromOauth - logout the currently authenticated oAuth user

Returns:

Promise

# Login button plugin methods

createLoginButton - creates Endpass login button instance

Params:

{
  element: string|HTMLElement,
  onLogin: Callback<{
    e?: Error,
    user: {
      id: string,
      email: string,
    }
  }>,
  isLight?: boolean,
  label?: string
}

Returns:

Promise

# Errors

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

const requestParams = {
  url: 'https://api.endpass.com/v1/user',
  method: 'GET',
};

(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.