# Authorize a connector using the Vault API

Apideck gives you three ways to let a customer authorize a connection: embed [Vault JS](/guides/vault) in your app, redirect to the Hosted Vault connection page, or build the flow entirely yourself using the `authorize_url` from the [Get Connections call](https://developers.apideck.com/apis/vault/reference#operation/connectionsAll). All three require a Vault Session first, since that session identifies which consumer is authorizing which service.

- [Vault JS](#option-1-vault-js): embed a pre-built connection UI in your app
- [Redirecting to Hosted Vault](#option-2-redirecting-to-the-hosted-vault-connection-page): send the customer to Apideck's hosted page
- [Completely built into your application](#option-3-completely-built-into-your-application): build your own UI on top of the `authorize_url`

## Option 1: Vault JS

[Vault JS](/guides/vault) embeds a pre-built connection UI directly in your app via an NPM package, handling every step of connecting a user to a service without you having to build your own UI.

We also have specific [React](/guides/vault-react) and [Vue](/guides/vue-vault) packages to make it even easier to integrate Vault into your application.

![React Vault](/guides/react-vault.jpg)

### Open Apideck Vault

```js
import { ApideckVault } from '@apideck/vault-js'

ApideckVault.open({
  token: 'REPLACE_WITH_SESSION_TOKEN',
  unifiedApi: 'accounting',
  serviceId: 'quickbooks'
})
```

You can find the `unifiedApi` and `serviceId` on the Connection object returned from the [Get Connections call](https://developers.apideck.com/apis/vault/reference#operation/connectionsAll).

## Option 2: Redirecting to the Hosted Vault connection page

Redirecting to Hosted Vault sends the customer to an Apideck-hosted page that handles the entire authorization flow, so you only need a call-to-action in your app that links to the connection page's URL.

The URL to redirect needs to be built up like this:

```json meta=URL
https://vault.apideck.com/integrations/<unified_api>/<service_id>?jwt=<token>
```

You can find the `unified_api` and `service_id` on the Connection object returned from the [Get Connections call](https://developers.apideck.com/apis/vault/reference#operation/connectionsAll). The `token` is the Vault Session token that gets returned after [creating a session](https://developers.apideck.com/apis/vault/reference#operation/sessionsCreate).

### Session settings

Two Vault Session settings control the Hosted Vault experience: `auto_redirect` sends the customer back to your application automatically once the connection's state becomes `callable`, and `settings.isolation_mode` (set to `true`) hides the "integrations overview" navigation link in the Hosted Vault UI.

![Isolation Mode](/guides/isolation_mode.jpg)

A `redirect_uri` is also required when creating the Vault Session, since Hosted Vault uses it as the redirect target.

```js meta=Example
fetch('https://unify.apideck.com/vault/sessions', {
  method: 'POST',
  headers: {
	  Authorization: `Bearer ${token}`,
	  'X-APIDECK-CONSUMER-ID': 'some-user-id',
	  'X-APIDECK-APP-ID': 'my-app-id'
	},
  body: {
     redirect_uri: 'https://my-application.com/', // <==== HERE
     settings: {
       auto_redirect: true,
	     isolation_mode: true
		 }
   })
})
```

See [sessionsCreate](https://developers.apideck.com/apis/vault/reference#operation/sessionsCreate) for the full list of session options.

## Option 3: Completely built into your application

Building the flow yourself means using the `authorize_url` field returned from the [Get Connections call](https://developers.apideck.com/apis/vault/reference#operation/connectionsAll) directly, without redirecting to any Apideck-hosted page.

Example **Get connection** response:

```jsx meta=Response
{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "service_id": "salesforce",
    "name": "Salesforce",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "unified_api": "crm",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "website": "https://www.salesforce.com",
    "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
    "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
    "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
    "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
    ...
  }
}
```

Appending a `redirect_uri` param to the `authorize_url` is required, and that param must be URL-encoded.

**Be aware:** redirecting back directly to your own application means you are responsible for handling any authorization errors and any additional connection configuration a customer might need. Hosted Vault handles both of those automatically; building your own flow means implementing them yourself.

![Additional configuration](/guides/additional-config.jpg)

Apideck recommends redirecting back to Hosted Vault instead, appending your Vault token to the URL like this:

```json meta=URL
"<authorize_url>&redirect_uri=https://vault.apideck.com/integrations/<unified_api>/<service_id>?jwt=<your-token>"
```

```json meta=Example
"https://unify.apideck.com/vault/authorize/officient-io/cfaZrORgaH2PMQpIcjTpfhERIpIEUJHev09ucjTp?state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zdW1lcl9pZCI6InRlc3QtY29uc3VtZXItY2tncnM5NWwzeTRlcjBiOTlxYTM3YnVqMiIsInVuaWZpZWRfYXBpIjoiY3JtIiwic2VydmljZV9pZCI6InBpcGVkcml2ZSIsImFwcGxpY2F0aW9uX2lkIjoiY2ZhWnJPUmdhSDJQTVFwSWNqVHBmaEVSSXBJRVVKSGV2MDl1Y2pUcCIsImlhdCI6MTY0NTQzNzc5MSwiZXhwIjoxNjQ1NTI0MTkxfQ.iuQeMcMIcbfYbD9a4Q40ShyQ0pEbYPd18Ay3ygJn3tQ&redirect_uri=https://vault.apideck.com/integrations/hris/officient-io?jwt=your-token"
```