Authorize a connector using the Vault API

Instead of redirecting directly to the Hosted Vault, you can use the Vault API to build custom solutions and integrate better with your own application. When using the Vault API to build your own implementation, there are multiple ways of allowing your customers to authorize connections:

Use React Vault
Redirect to Hosted Vault
Completely build into your own app

Before we go over the different solutions it’s important to know that it’s required to obtain a Vault Session. This session is needed to identify the consumer that wants to connect to one or more services.

Option 1: Vault JS

Inside your application you can use Vault JS to quickly provide an embedded experience for your customers. With a simple NPM install, you can have a component that will handle every step of connecting your users to the desired service.

We also have specific React and Vue packages to make it even easier to integrate Vault into your application.

Open Apideck Vault


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.

Option 2: Redirecting to the Hosted Vault connection page

When you want your customer to authorize a specific connection, you can add a call-to-action in your application that redirects to a connection page of Hosted Vault.

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


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

token

is the Vault Session token that gets returned after creating a session.

Session settings

When creating a Vault Session you can provide a few settings to improve the customer experience.

Using the

auto_redirect

setting, you can tell Hosted Vault to automatically redirect back to your application when the connection has been updated and its state has become

callable

You can combine this by setting

settings.isolation_mode

true

to ensure the navigation link that points to the “integrations overview" is hidden from in the UI of Hosted Vault.

When creating your Vault Session it’s important to ensure you have provided a

redirect_uri

, which will be used to redirect.


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
		 }
   })
})

For all the session options you can provide, go here: sessionsCreate

Option 3: Completely built into your application

If you want to authorize a connection without leaving your application, you could use the

authorize_url

that is being returned from the Get Connections call directly.

Example Get connection 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>",
    ...
  }
}

If you do so, you have to append a

redirect_uri

param to the

authorize_url

, be sure to URL encode the

redirect_uri

param.

Be aware: By doing this, you can redirect back directly to your application, but you’ll need to handle any potential errors yourself. It could also be that a connection still needs some additional configuration from your customer. Hosted Vault can handle this for you, but if you redirect to your own application, you will need to build it yourself.

For this reason, we usually recommend redirecting back to Hosted Vault. If you do, ensure you append your vault token. The complete URL you will have to use should look something like this:


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


"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"