We launched the Accounting Sample!Manage invoices, payments, expenses, and more across multiple connectors.

Search docs

Authorizing 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: React Vault

If your application is built with React, we recommend using React Vault to quickly provide an embedded experience for your customers. It will create a valid Vault Session and handle every step of connecting to the desired service.

React Vault
React Vault

Render Vault

When rendering the <Vault/> component, you can provide the unifiedApi and serviceId to the component to open the modal specifically for that connection. When they are not present it will show all the connectors you have made available.

MyComponent.js
import { Vault } from '@apideck/react-vault'

const MyComponent = () => {
  return (
    <Vault
      token={token}
      unifiedApi="accounting"
      serviceId="quickbooks"
      trigger={<button>Connect with QuickBooks</button>}
    />
  )
}

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:

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

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.

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

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:

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

URL
"<authorize_url>&redirect_uri=https://vault.apideck.com/integrations/<unified_api>/<service_id>?jwt=<your-token>"
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"