Manage API keys, access tokens, OAuth flows and integrations.

Vault API

x-apideck-app-id

application_id

An authorization code from the connector which Apideck Vault will later exchange for an access token.

code

Scopes results to connections that have been configured or not

configured

ID of the consumer which you want to get or push data from

x-apideck-consumer-id

consumer_id

filter

Cursor to start from. You can find cursors for next/previous pages in the meta.cursors property of the response.

cursor

Scopes results to requests that happened before datetime

end_datetime

Number of results to return. Minimum 1, Maximum 200, Default 20

limit

Include raw response. Mostly used for debugging purposes

URL to redirect back to after authorization. When left empty the default configured redirect uri will be used.

redirect_uri

The redirect uri to redirect to after the revoke flow is completed.

resource

This is the id of the resource you want to fetch when listing custom fields. For example, if you want to fetch custom fields for a specific contact, you would use the contact id.

resource_id

One or more OAuth scopes to request from the connector. OAuth scopes control the set of resources and operations that are allowed after authorization. Refer to the connector's documentation for the available scopes.

scope

service_id

Scopes results to requests that happened after datetime

start_datetime

An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks.

state

ID of the target field to return as a custom mapping.

target_field_id

unified_api

Downstream authorization header. This will skip the Vault token injection.

x-apideck-downstream-authorization

Downstream method. If not provided the upstream method will be inherited,

x-apideck-downstream-method

x-apideck-downstream-url

Provide the service id you want to call (e.g., pipedrive). Only needed when a consumer has activated multiple integrations for a Unified API.

x-apideck-service-id

Consumers Request Counts within Date Range

Indicates if the error returned in the body is from the downstream

Type of authorization used by the connector

Contains parameter or domain specific information related to the error and why it occurred.

Contains downstream errors returned from the connector. Only present when type_name is ConnectorExecutionError.

Contains an explanation of the status_code as defined in HTTP/1.1 standard (RFC 7231)

A human-readable message providing more details about the error.

The confirm token received from the OAuth callback redirect.

The OAuth redirect URI. Redirect your users to this URI to let them authorize your app in the connector's UI. Before you can use this URI, you must add `redirect_uri` as a query parameter to the `authorize_url`. Be sure to URL encode the `redirect_uri` part. Your users will be redirected to this `redirect_uri` after they granted access to your app in the connector's UI.

Immutable array of consent records for compliance and audit purposes

Unix timestamp in milliseconds when credentials will be deleted if token refresh continues to fail. A value of 0 indicates no active retention window (connection is healthy or not using OAuth token refresh).

List of custom mappings configured for this connection

Whether the connection is enabled or not. You can enable or disable a connection using the Update Connection API.

The settings that are wanted to create a connection.

Whether the connector has a guide available in the developer docs or not (https://docs.apideck.com/connectors/{service_id}/docs/consumer+connection).

Operational health status of the connection

A visual icon of the connection, that will be shown in the Vault

Unix timestamp in milliseconds of the last failed token refresh attempt. A value of 0 indicates no recent failures. This field is used internally to enforce cooldown periods between retry attempts.

The logo of the connection, that will be shown in the Vault

The OAuth revoke URI. Redirect your users to this URI to revoke this connection. Before you can use this URI, you must add `redirect_uri` as a query parameter. Your users will be redirected to this `redirect_uri` after they granted access to your app in the connector's UI.

The ID of the service this connection belongs to.

List of settings that are required to be configured on integration before authorization can occur

The unified API category where the connection belongs to.

The service provider's ID of the entity that triggered this event

The type entity that triggered this event

The current count this request event has been attempted

ISO Datetime for when the original event occurred

The operational health status of the connection

The number of seconds until the token expires. If omitted the token will be queued for refresh.

The datetime at which the token was issued. If omitted the token will be queued for refresh.

The refresh token can be used to obtain a new access token.

[Connection state flow](#section/Connection-state)

The date and time when the object was created.

Created at (timestamp)

The delivery url of the webhook endpoint. The endpoint must respond within 60 seconds or the delivery is recorded as failed.

Description

Indicates why the webhook has been disabled. `retry_limit`: webhook reached its retry limit. `usage_limit`: account is over its usage limit. `delivery_url_validation_failed`: delivery URL failed validation during webhook creation or update.

The list of subscribed events for this webhook. [`*`] indicates that all events are enabled.

Subscribed events

The Unify Base URL events from connectors will be sent to after service id is appended.

The date and time when the object was last updated.

Updated at (timestamp)

Whether consent was granted (true) or denied/revoked (false)

Unique identifier for this consent record

The current consent state of the connection

ISO 8601 timestamp indicating when credentials will be cleared if token refresh continues to fail. Only present when connection health is pending_refresh and a retention window is active.

ISO 8601 timestamp of the most recent token refresh failure. Only present when connection has experienced refresh failures.

Unique consumer identifier. You can freely choose a consumer ID yourself. Most of the time, this is an ID of your internal data model that represents a user or account in your system (for example account:12345). If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID.

The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.

The name of the account as shown in the sidebar.

Account name

The email of the user as shown in the sidebar.

Email

The avatar of the user in the sidebar. Must be a valid URL

Image

The name of the user as shown in the sidebar.

User name

Filter by consumer ID using a prefix match (beginsWith).

Search across consumer ID, email, account name, and user name using a substring match (contains). Matches any field (OR logic).

The redirect URI to be used after the connection is created.

JSONPath finder for retrieving this value when mapping a response payload from downstream

Custom Field name to use as a label if provided

This mapping represents a finder for a custom field

Target Field Mapping example value from downstream

Whether Data Scopes is enabled for this application

ISO timestamp of when the Data Scopes configuration was last modified

Data scopes resource configuration that can be either detailed field permissions or a wildcard

Map of resources to field-level permissions

Wildcard indicating all resources and fields when Data Scopes is selected

Only applicable to select fields. Allow the user to add a custom value though the option select if the desired value is not in the option select list.

Allow custom values

When the setting is deprecated, it should be hidden from the user interface. The value will still be stored on the connection for the sake of backwards compatibility.

Indicates if the form field is displayed in a “read-only” mode.

Indicates if the form field is not displayed but the value that is being stored on the connection.

Prefix to display in front of the form field.

Indicates if the form field is required, which means it must be filled in before the form can be submitted

Indicates if the form field contains sensitive data, which will display the value as a masked input.

Suffix to display next to the form field.

ID of the resource in the Connector's API (downstream)

Name of the resource in the Connector's API (downstream)

Links to navigate to previous or next pages through the API

Link to navigate to the current page through the API

Link to navigate to the previous page through the API

Indicates if the request was made via REST or Graphql endpoint.

The Apideck base URL the request was made to.

Indicates whether or not this is a child or parent request.

The consumer Id associated with the request.

The entire execution time in milliseconds it took to call the Apideck service provider.

If error occurred, this is brief explanation

The entire execution time in milliseconds it took to make the request.

When request is a parent request, this indicates if there are child requests associated.

Latency added by making this request via Unified Api.

The OpenApi Operation Id associated with the request

The OpenApi Operation name associated with the request

When request is a child request, this UUID indicates it's parent request.

The path component of the URI the request was made to.

Indicates whether the request was made using Apidecks sandbox credentials or not.

Apideck service provider associated with request.

The IP address of the source of the request.

Whether or not the request was successful.

ISO Date and time when the request was made.

Filter by a single HTTP status code. For backward compatibility - use status_codes for multiple values.

Filter by multiple HTTP status codes. Values must be between 100-599. Maximum 50 status codes allowed.

OAuth grant type used by the connector. More info: https://oauth.net/2/grant-types

This is the ship that made the Kessel Run in fourteen parsecs?

Raw response from the integration when raw=true query param is provided

ID of the resource, typically a lowercased version of name.

Status of the resource. Resources with status live or beta are callable.

Custom consumer settings that are passed as part of the session.

Custom consumer settings

The URL to redirect the user to after the session has been configured.

Redirect URI

Whether consent is being granted (true) or denied/revoked (false)

Map of resources to field-level permissions that are being consented to

Wildcard indicating all resources and fields when Data Scopes is disabled

The date and time the webhook subscription was created downstream

The list of downstream Events this connection is subscribed to

The URL the downstream is sending to when the event is triggered

The list of Unify Events this connection is subscribed to

To access our API, you need to sign up and obtain your unique API key. Each Unify application is assigned a single API key. You can locate your API key in the Configuration Settings section of your Apideck application. Additionally, your application’s application_id is available on the same page.

Authenticate your API requests by including your test or live secret API key in the request header.

- Bearer authorization header: `Authorization: Bearer "YOUR_API_KEY_HERE"`
- Application id header: `x-apideck-app-id: "YOUR_APP_ID_HERE"`

You should use the public keys on the SDKs and the secret keys to authenticate API requests.

**Do not share or include your secret API keys on client side code.** Your API keys carry significant privileges. Please ensure to keep them 100% secure and be sure to not share your secret API keys in areas that are publicly accessible like GitHub.

Learn how to set the Authorization header inside Postman https://learning.postman.com/docs/postman/sending-api-requests/authorization/#api-key

Go to Unify to grab your API KEY https://app.apideck.com/unify/api-keys


Authorization

Welcome to the Vault API 👋

When you're looking to connect to an API, the first step is authentication.

Vault helps you handle OAuth flows, store API keys, and refresh access tokens from users (called consumers in Apideck).

## Base URL

The base URL for all API requests is `https://unify.apideck.com`

## Get Started

To use the Apideck APIs, you need to sign up for free at [https://app.apideck.com/signup](). Follow the steps below to get started.

- [Create a free account.](https://app.apideck.com/signup)
- Go to the [Dashboard](https://app.apideck.com/unify/unified-apis/dashboard).
- Get your API key and the application ID.
- Select and configure the integrations you want to make available to your users. Through the Unify dashboard, you can configure which connectors you want to support as integrations.
- Retrieve the client_id and client_secret for the integration you want to activate (Only needed for OAuth integrations).
- Register the redirect URI for the example app (https://unify.apideck.com/vault/callback) in the list of redirect URIs under your app's settings.

### Vault JS

[Vault JS](https://developers.apideck.com/guides/vault) is a vanilla JavaScript library to embed Apideck Vault in any web application.

[Follow this guide](https://developers.apideck.com/guides/vault) to get started

### Hosted Vault

Hosted Vault (vault.apideck.com) is a no-code solution, so you don't need to build your own UI to handle the integration settings and authentication.

![Hosted Vault - Integrations portal](https://github.com/apideck-samples/integration-settings/raw/master/public/img/vault.png)

Behind the scenes, Hosted Vault implements the Vault API endpoints and handles the following features for your customers:

- Add a connection
- Handle the OAuth flow
- Configure connection settings per integration
- Manage connections
- Discover and propose integration options

To use Hosted Vault, you will need to first [**create a session**](https://developers.apideck.com/apis/vault/reference#tag/Sessions/operation/sessionsCreate). This can be achieved by making a POST request to the Vault API to create a valid session for a user, hereafter referred to as the consumer ID.

### Vault API

_Beware, this strategy takes more time to implement in comparison to Vault JS and Hosted Vault._

If you are building your integration settings UI manually, you can call the Vault API directly.

The Vault API is for those who want to completely white label the in-app integrations overview and authentication experience. All the available endpoints are listed below.

Through the API, your customers authenticate directly in your app, where Vault will still take care of redirecting to the auth provider and back to your app.

If you're already storing access tokens, we will help you migrate through our Vault Migration API.

## Domain model

At its core, a domain model creates a web of interconnected entities.

Our domain model contains five main entity types: Consumer (user, account, team, machine), Application, Connector, Integration, and Connection.

## Connection state

The connection state is computed based on the connection flow below.

![](https://developers.apideck.com/api-references/vault/connection-flow.png)

## Unify and Proxy integration

The only thing you need to use the Unify APIs and Proxy is the consumer id; thereafter, Vault will do the look-up in the background to handle the token injection before performing the API call(s).

## Headers

Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230) states header names are case insensitive.

| Name | Type | Required | Description | | --- | --- | --- | --- | | x-apideck-app-id | String | Yes | The id of your Unify application. Available at https://app.apideck.com/api-keys. | | x-apideck-consumer-id | String | Yes | The id of the customer stored inside Apideck Vault. This can be a user id, account id, device id or whatever entity that can have integration within your app. | | x-apideck-raw | Boolean | No | Include raw response. Mostly used for debugging purposes. |

## Webhook Events

Vault provides real-time webhook events to notify you of connection state changes:

- **vault.connection.created** - Triggered when a new connection is created in Vault - **vault.connection.updated** - Triggered whenever any connection data changes (credentials, settings, metadata) - **vault.connection.callable** - Triggered when a connection transitions to callable state (ready for API calls) - **vault.connection.disabled** - Triggered when the enabled property changes from true to false - **vault.connection.deleted** - Triggered when a connection is permanently removed from the system - **vault.connection.revoked** - Triggered when OAuth access is successfully revoked at the service provider level - **vault.connection.token_refresh.failed** - Triggered when automatic token refresh fails for an OAuth connection

### Event Sequences

**Initial OAuth Flow:** 1. `vault.connection.created` (if new connection) 2. `vault.connection.updated` (when OAuth credentials are saved) 3. `vault.connection.callable` (when connection becomes ready for API calls)

**Re-authorization:** 1. `vault.connection.updated` (when new credentials are saved) 2. `vault.connection.callable` (if connection becomes callable again)

**Connection Management:** - **Disabled**: `vault.connection.disabled` (connection paused but preserved) - **Deleted**: `vault.connection.deleted` (permanent removal) - **Revoked**: `vault.connection.revoked` (OAuth access revoked at service provider)

## Guides

- [How to integrate Vault JS](https://developers.apideck.com/guides/vault)
- [How to build an integrations UI with Vault](https://github.com/apideck-samples/vault?tab=readme-ov-file#integration-settings)

## How to integrate Apideck Vault

Vault provides **three auth strategies** to use API tokens from your customers:

- [Vault JS](https://developers.apideck.com/guides/vault) (recommended)
- Vault API
- Hosted Vault (advanced)

### What auth types does Vault support?

We currently support three authentication flows for your customers to activate an integration:

#### API keys

For services supporting the API key strategy, Hosted Vault provides an in-app form where users can configure their API keys provided by the integration service.

#### OAuth 2.0

Vault handles the complete Authorization Code Grant Type Flow for you. This flow only supports browser-based (passive) authentication because most identity providers don't allow entering a username and password to be entered into applications that they don't own.

Certain connectors require an OAuth redirect authentication flow, where the end-user is redirected to the provider's website or mobile app to authenticate. This is handled by the `/authorize` endpoint.

#### Basic auth

Basic authentication is a simple authentication scheme built into the HTTP protocol. The required fields to complete basic auth are handled by Hosted Vault or by updating the connection through the Vault API.

You can learn more about [API Auth methods](https://www.apideck.com/blog/api-auth-authentication-methods-and-examples) in our guide.

## FAQ

**What purpose does Vault serve? Can I just handle the authentication and access token myself?**

You can store everything yourself, but that defeats the purpose of using Apideck Unify. Handling tokens for multiple providers can quickly become very complex.

### Is my data secure?

Vault employs data minimization, therefore only requesting the minimum amount of scopes needed to perform an API request.

### How do I migrate existing data?

Using our migration endpoints, you can [import access tokens and accounts](https://developers.apideck.com/guides/migrating-integrations) to Apideck Vault.

### Can I use Vault in combination with existing integrations?

Yes, you can. The flexibility of Unify allows you to quickly use the cases you need while keeping a gradual migration path based on your timeline and requirements.

### Webhook Event Differences

**What's the difference between disabled, deleted, and revoked?**

- **Disabled**: Connection is paused but preserved (enabled=false). Can be re-enabled. - **Deleted**: Connection is permanently removed from the system. Cannot be recovered. - **Revoked**: OAuth access is revoked at the service provider level. Connection record remains but requires re-authorization.

**When do I get multiple events during OAuth?**

During re-authorization, you typically receive: 1. `vault.connection.updated` (when new credentials are saved) 2. `vault.connection.callable` (if connection becomes callable again)

**What's the difference between updated and callable events?**

- `updated` fires on any change to connection data - `callable` only fires when the connection state changes TO callable - Think of `callable` as a significant milestone, while `updated` is any change


Apache 2.0

__In most cases the authorize link is provided in the ``/connections`` endpoint. Normally you don't need to manually generate these links.__

Use this endpoint to authenticate a user with a connector. It will return a 301 redirect to the downstream connector endpoints.

Auth links will have a state parameter included to verify the validity of the request. This is the url your users will use to activate OAuth supported integration providers.

Vault handles the complete Authorization Code Grant Type Flow for you and will redirect you to the dynamic redirect uri you have appended to the url in case this is missing the default redirect uri you have configured for your Unify application.


This endpoint gets called after the triggering the authorize flow.

Callback links need a state and code parameter to verify the validity of the request.

When an error occurs during the OAuth flow, providers will optionally include error parameters
in the callback request instead of the code parameter.


Error code returned by the OAuth provider when authorization fails

error

Human-readable description of the error from the OAuth provider

error_description

This endpoint includes all the configured integrations and contains the required assets
to build an integrations page where your users can install integrations.
OAuth2 supported integrations will contain authorize and revoke links to handle the authentication flows.


Fields that need to be updated on the resource

Fields that need to be persisted on the resource

This endpoint creates a callback state that can be used to issue requests to the callback endpoint.


Confirms an OAuth connection after the callback by verifying the confirm token.


Triggers exchanging persisted connection credentials for an access token and store it in Vault. Currently supported for connections with the `client_credentials` or `password` OAuth grant type.

Note:
  - Do not include any credentials in the request body. This operation does not persist changes, but only triggers the exchange of persisted connection credentials for an access token.
  - The access token will not be returned in the response. A 200 response code indicates the authorization was successful and that a valid access token was stored on the connection.
  - The access token will be used for subsequent API requests.


This endpoint validates the current state of a given connection. This will perform different checks based on the connection auth type. For basic and apiKey auth types, the presence of required fields is checked.
For connectors that implement OAuth2, this operation forces the refresh flow for an access token regardless of its expiry.

Note:
  - Do not include any credentials in the request body. This operation does not persist changes, but only triggers the validation of connection state.
  - If a refresh token flow was performed and successful, the new access token will then be used for subsequent API requests.


This endpoint returns custom settings and their defaults required by connection for a given resource.


Update default values for a connection's resource settings

This endpoint returns an custom fields on a connection resource.


This endpoint returns a list of custom mappings for a connection.

This endpoint returns a downstream example of a given resource.


This endpoint returns an approximate JSONSchema of a given resource.


This endpoint includes all application consumers, along with an aggregated count of requests made.


Delete consumer and all their connections, including credentials.

Consumer detail including their aggregated counts with the connections they have authorized.


Update consumer metadata such as name and email.

Get consumer request counts within a given datetime range.


This endpoint returns a list of custom mappings.

This endpoint includes all consumer request logs.


Endpoint that receives browser redirect notifications from downstream providers
when a user disconnects their OAuth integration. The JWT in the path encodes
the application identity. The service_id identifies the connector.


Redirect to the application's configured post-disconnect URL

Endpoint that receives server-to-server POST callbacks from downstream providers
when a user disconnects their OAuth integration. The JWT in the path encodes
the application identity. The service_id identifies the connector. The request
body contains the provider-specific identifier.


__In most cases the authorize link is provided in the ``/connections`` endpoint. Normally you don't need to manually generate these links.__

Use this endpoint to revoke an existing OAuth connector.

Auth links will have a state parameter included to verify the validity of the request. This is the url your users will use to activate OAuth supported integration providers.

Vault handles the complete revoke flow for you and will redirect you to the dynamic redirect uri you have appended to the url.


Making a POST request to this endpoint will initiate a Hosted Vault session. Redirect the consumer to the returned
URL to allow temporary access to manage their integrations and settings.

Note: This is a short lived token that will expire after 1 hour (TTL: 3600).


Additional redirect uri and/or consumer metadata

Event broadcast when a connection is now callable.

x-apideck-event-type

HMAC SHA-256 signature of the request body, used to verify the webhook came from Apideck

Connection

Resource not found