Understanding Vault and Authentication

Vault is how your users connect their integrations through Apideck. This article gives you a conceptual overview of how Vault works and the different ways to integrate it. For specific how-to guides on topics like custom fields, CORS troubleshooting, and token management, see the dedicated Vault section of this help center.

• What Vault does

• How authentication works

• Three ways to integrate Vault

• Creating consumer sessions

• Going to production with your own OAuth apps

When your user wants to connect their Salesforce, QuickBooks, or any other supported platform, they do it through Vault. Vault handles the entire authentication process — OAuth redirects, token storage, token refresh, and error handling — so you don't have to.

Each connection is scoped to a consumer (your end user). This means User A's Salesforce connection is completely isolated from User B's. Vault stores credentials securely, and you never need to see or manage access tokens directly.

Want to use existing tokens? If you're migrating from another integration provider or managing your own tokens, you can import them into Vault. See the Migrating Integrations guide in the developer docs.

Here's what happens when a user connects an integration:

1. Your app creates a Vault session for the consumer (a server-side API call).

2. The consumer is presented with the Vault UI, where they select an integration and click Authorize.

3. Vault redirects the user to the provider's OAuth consent screen.

4. The user authorizes access, and the provider redirects back to Vault.

5. Vault stores the tokens securely and marks the connection as authorized.

6. Your app can now make Unified API calls on behalf of that consumer.

Vault handles token refresh automatically. If an access token expires, Apideck refreshes it before processing your API call, no action needed on your side.

Connections go through several states during this flow (available, added, authorized, callable, etc.). For a full breakdown of each state and what it means, see the Vault Connection States guide in the developer docs.

Vault JS is a lightweight JavaScript library that opens Vault as a modal inside your application. It's the fastest way to provide a seamless, embedded experience. We also provide framework-specific packages for React (@apideck/react-vault) and Vue (@apideck/vue-vault).

For installation and configuration, see the Vault JS developer guide.

Hosted Vault is a standalone, Apideck-hosted page where your users manage their integrations. It requires no frontend code, you simply redirect users to a URL. You can customize its appearance with your brand colors, logo, and more.

To try it: Go to the Vault page in your dashboard and click Launch Demo.

If you need full control over the UI, you can use the Vault API directly to build a completely custom integrations page. This approach requires more development effort but gives you total flexibility.

For guidance on building custom authorization flows, see the Authorizing Connections guide.

Regardless of which Vault integration you choose, you need to create a session for each consumer. This is a server-side API call that returns a session token (JWT).

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}' \
  --data-raw '{
    "redirect_uri": "https://yourapp.com/dashboard",
    "consumer_metadata": {
      "account_name": "Acme Corp",
      "user_name": "Jane Smith"
    }
  }'

Key points:

• Consumer IDs must be unique. Use an identifier from your own system, like account:12345. If the consumer doesn't exist yet, Apideck creates one automatically.

• Always create sessions server-side to prevent your API key from being exposed.

• The session token is short-lived - generate a new one each time a user needs to access Vault.

When creating a session, you can pass settings to tailor the experience: limit to specific APIs or a single connector, set a redirect URI, apply branding, and control which actions users can perform. For the full list, see the Vault API reference.

For some connectors, Apideck provides sandbox OAuth apps so you can test authorization flows without any setup. When you enable a connector in the dashboard, you'll see an option to "Use Apideck credentials", this lets you start testing right away.

In production, you'll need your own OAuth credentials. How you get them depends on the provider:

• Some providers let you register a developer app and get credentials in minutes.

• Others require a formal partnership agreement, app review, or certification process that can take several weeks.

Check the connector-specific guide in the Apideck developer portal or the provider's developer documentation early to understand their requirements and avoid delays. Once you have your credentials, add them per connector in the Apideck dashboard under Configuration.

For a full pre-launch walkthrough, see Going to Production: A Checklist.

The Vault section of this help center covers specific scenarios including:

• Using existing access tokens from integrations via Apideck

• Mapping custom fields in Vault

• Handling CORS errors

• Managing multiple connections for the same connector

• Detecting when integrations get connected or disconnected

Related resources:

• Vault section of this help center

• Developer docs: Vault guide

• Developer docs: Authorizing connections

• Developer docs: Connection states

• Vault API reference