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.

React Vault
React Vault

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
to
true
to ensure the navigation link that points to the “integrations overview" is hidden from in the UI of Hosted Vault.

Isolation Mode
Isolation Mode

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.

Additional configuration
Additional configuration

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"