Vault React

Vault React is an NPM package that allows you to embed Apideck Vault into your React application. You can easily let your users authorize and manage integration settings. It makes credential handling more secure and seamless.

This guide will get you up and running with the Vault React hook. To get started, follow these 3 steps:

Step 1: Setup Apideck

Create an account

If you haven't already, head over to our Signup page and create an account. Choose an application name and a subdomain. Afterward, you will be redirected to the Apideck dashboard.

Enable Unified APIs and connectors

Go to the Unified APIs page in the Apideck dashboard. Choose one or more Unified APIs to enable. You'll see a list of the available connectors for each Unified API. Choose a couple of connectors to enable. The Unified APIs and connectors you select become available to your users in Vault.

Get your API key and Application ID

Go to the API Keys page in the Apideck dashboard. Copy your application ID and API key. If your API key ever gets compromised, you can regenerate it on this page.

API keys overview
API keys overview

Step 2: Create a session

Vault lets your users (called consumers in Apideck) easily connect and configure integrations. You can create a consumer through a Vault session through the following endpoint https://developers.apideck.com/apis/vault/reference#tag/Sessions.

Most of the time, this is an ID of your internal data model that represents a user or account in your system. E.g., account:12345. If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID.

Use the API call below to create a session for a consumer. This will return a Vault URL that you forward to a consumer to connect integrations.

curl --request POST \
  --url 'https://unify.apideck.com/vault/sessions' \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'x-apideck-app-id: {APP_ID}' \
  --header 'x-apideck-consumer-id: {CONSUMER_ID}' \

You can also use our Node SDK to create a session.

yarn add @apideck/node

Below is an example of creating a Serverless Function to create a session inside a Next.js project:

import { VercelRequest, VercelResponse } from '@vercel/node'
import { Apideck } from '@apideck/node'

const createSession = async (_: VercelRequest, res: VercelResponse) => {
  const apideck = new Apideck({
    apiKey: `${process.env.API_KEY}`,
    appId: `${process.env.APP_ID}`,
    consumerId: 'test-consumer'
  })
  const settings = {}
  const { data } = await apideck.vault.sessionsCreate(settings)

  res.json(data)
}

export default createSession

The returned

data
object will include the
session_token
that you can use pass as the
jwt
prop to the
open
function from the
useVault
hook. It also includes a
session_uri
, which is a link to the Hosted Vault application. You can use this link if you don't want to use
vault-react
and redirect the user to the hosted solution.

Step 3: Add Vault React

Vault lets your users authorize connectors and manage integration settings. It stores the credentials securely and lets you make authorized API calls on your consumers` (users) behalf. To get started, install the component using NPM or Yarn.

yarn add @apideck/vault-react

Next, import the

useVault
hook pass the JSON Web Token to the
open
function.

import { useVault } from '@apideck/vault-react'

function App() {
  const { open } = useVault()

  return <button onClick={() => open({ token: 'REPLACE_WITH_SESSION_TOKEN' })}>Open Vault</button>
}

export default App

If you want to only show integrations for a single Unified API, you can do that by passing the

unifiedApi
prop. If you want to open Vault for only a single integration, you can provide the
serviceId
prop.

import { useVault } from '@apideck/vault-react'

function App() {
  const { open } = useVault()

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          unifiedApi: 'file-storage',
          serviceId: 'dropbox'
        })
      }
    >
      Open Vault
    </button>
  )
}

export default App

If you want to get notified when the modal opens and closes, you can provide the

onReady
and
onClose
options. You can also provide the
onConnectionChange
and
onConnectionDelete
options to get notified when the state of a connection changes or gets deleted.

import { useVault } from '@apideck/vault-react'

function App() {
  const { open } = useVault()

  function onClose() {
    console.log('close!')
  }

  function onReady() {
    console.log('ready!')
  }

  function onConnectionChange(connection: Connection) {
    console.log('changed!', connection)
  }

  function onConnectionDelete(connection: Connection) {
    console.log('ready!', connection)
  }

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          onReady,
          onClose,
          onConnectionChange,
          onConnectionDelete
        })
      }
    >
      Open Vault
    </button>
  )
}

export default App

If you want to open a specific view you can pass the

initialView
prop. The available views are
settings
,
configurable-resources
, and
custom-mapping
.

import { useVault } from '@apideck/vault-react'

function App() {
  const { open, close } = useVault()

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          unifiedApi: 'accounting',
          serviceId: 'quickbooks',
          initialView: 'custom-mapping'
        })
      }
    >
      Open Vault
    </button>
  )
}

If you want to open Vault in a specific language you can add the

locale
prop. The available locales are
en
(default),
nl
,
de
,
fr
, and
es
.

import { useVault } from '@apideck/vault-react'

function App() {
  const { open, close } = useVault()

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          locale: 'nl'
        })
      }
    >
      Open Vault
    </button>
  )
}

If you want to show the language switch at the bottom of Vault you can add the

showLanguageSwitch
prop.

import { useVault } from '@apideck/vault-react'

function App() {
  const { open, close } = useVault()

  return (
    <button
      onClick={() =>
        open({
          token: 'REPLACE_WITH_SESSION_TOKEN',
          locale: 'nl',
          showLanguageSwitch: true
        })
      }
    >
      Open Vault
    </button>
  )
}

Demo

The code block below shows a quick demo on how you could use the Vault component. Click the button to execute the code that's shown below.

Loading

Properties

PropertyTypeRequiredDefaultDescription
tokenstringtrue-The JSON Web Token returned from the Create Session API
showAttributionbooleanfalsetrueShow "Powered by Apideck" in the backdrop of the modal backdrop
onClose() => voidfalse-Function that gets called when the modal is closed
onReady() => voidfalse-Function that gets called when the modal is opened
onConnectionChange(connection: Connection) => voidfalse-Function that gets called when the user updates a connection. This can be linking their account, filling out settings or adding a new connection
onConnectionDelete(connection: Connection) => voidfalse-Function that gets called when the user deletes a connection
unifiedApistringfalse-When unifiedApi is provided it will only show integrations from that API.
serviceIdstringfalse-When unifiedApi and serviceId are provided Vault opens a single integration
initialViewConnectionViewTypefalse-Open Vault in a specific view for a connection session
localestringfalse"en"Open Vault in a specific language: "en", "nl", "de", "fr" or "es"
showLanguageSwitchbooleanfalsefalseShow language switch at bottom