# Vue Vault

A Vue component to embed [Apideck Vault](https://www.apideck.com/products/vault) in any Vue application.

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

- [Step 1: Setup Apideck](#step-1-setup-apideck)
- [Step 2: Create a session](#step-2-create-a-session)
- [Step 3: Add Vue Vault](#step-3-add-vue-vault)

## Step 1: Setup Apideck

### Create an account

If you haven't already, head over to our [Signup page](https://www.apideck.com/signup?products=unify&source=docs-react-vault) 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](https://platform.apideck.com) 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](https://developers.apideck.com/apis/vault/reference).

### Get your API key and Application ID

Go to the [API Keys](https://platform.apideck.com/configuration/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](/get-started/api-keys.png)

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

> **Note 🚨**
>
> Session creation should always happen server-side to prevent token leakage.

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.

```sh meta=terminal
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 one of our [SDKs](/sdks/node) to create a session, like for example the Node SDK:

```sh meta=terminal
npm install @apideck/unify
```

Below is an example of creating a function to create a session:

```ts meta=/api/vault/sessions.ts
import { Apideck } from '@apideck/unify'

const createSession = async (_, res) => {
  const apideck = new Apideck({
    apiKey: process.env.API_KEY ?? '',
    appId: process.env.APP_ID ?? '',
    consumerId: 'test-consumer'
  })
  const settings = {}
  const { data } = await apideck.vault.sessions.create({
    session: 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 `Vault` component.
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 `react-vault` and redirect the user to the hosted solution.

### Customizing the session

When creating a session, you can customize the Vault experience by providing various settings, for example:

```js
const settings = {
  allow_actions: ['delete', 'disconnect', 'reauthorize'], // Leave empty to hide all.
  hide_resource_settings: true, // Hide configurable resources for integrations
  unified_apis: ['crm', 'accounting'], // Only show these APIs (omit to show all)
  session_length: '1h', // Valid duration (max: 1 week)
  hide_guides: true // Hide Apideck connection guides
}
```

For all available settings and descriptions, see the [Vault API documentation](https://developers.apideck.com/apis/vault/reference#tag/Sessions/operation/sessionsCreate).

## Step 3: Add Vue Vault

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

### Package

```sh
npm install @apideck/vue-vault
```

### Usage

Pass the JWT you got from the Vault session to `@apideck/vue-vault`, call the slot prop `open` to open the Vault modal.

```vue
<script setup lang="ts">
import { VueVault } from '@apideck/vue-vault'

const sessionJwt = 'REPLACE_WITH_SESSION_TOKEN'
</script>

<template>
  <main>
    <VueVault :token="sessionJwt" v-slot="vaultProps">
      <button @click="vaultProps.open()">Open</button>
    </VueVault>
  </main>
</template>
```

If you want to only show integrations for a single Unified API, you can do that by passing the `unified-api` prop. If you want to open Vault for only a single integration, you can provide the `service-id` prop.

```vue
<script setup lang="ts">
import { VueVault } from '@apideck/vue-vault'

const sessionJwt = 'REPLACE_WITH_SESSION_TOKEN'
</script>

<template>
  <main>
    <VueVault
      :token="sessionJwt"
      unified-api="accounting"
      service-id="quickbooks"
      v-slot="vaultProps"
    >
      <button @click="vaultProps.open()">Open</button>
    </VueVault>
  </main>
</template>
```

If you want to get notified when the modal opens and closes, you can provide the `onReady` and `onClose` options.

```vue
<script setup lang="ts">
import { VueVault } from '@apideck/vue-vault'

const sessionJwt = 'REPLACE_WITH_SESSION_TOKEN'

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

function onReady() {
  console.log('ready!')
}
</script>

<template>
  <main>
    <VueVault :token="sessionJwt" :on-close="onClose" :on-ready="onReady" v-slot="vaultProps">
      <button @click="vaultProps.open()">Open</button>
    </VueVault>
  </main>
</template>
```

### Props

| Property           | Type    | Required | Default | Description                                                                                                                       |
| ------------------ | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| token              | string  | true     | -       | The JSON Web Token returned from the [Create Session API](https://docs.apideck.com/apis/vault/reference#operation/sessionsCreate) |
| show-attribution   | boolean | false    | true    | Show "Powered by Apideck" in the backdrop of the modal backdrop                                                                   |
| on-close           | event   | false    | -       | Function that gets called when the modal is closed                                                                                |
| on-ready           | event   | false    | -       | Function that gets called when the modal is opened                                                                                |
| unified-api        | string  | false    | -       | When unified-api is provided it will only show integrations from that API.                                                        |
| service-id         | string  | false    | -       | When unified-api and service-id are provided Vault opens a single integration                                                     |
| show-button-layout | boolean | false    | false   | Use button layout instead of dropdown menu in TopBar for connection actions                                                       |

### Demo

See a working demo [here](https://vault-demo.apideck.com/)