Vault API
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…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
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.
- Go to the 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 is a vanilla JavaScript library to embed Apideck Vault in any web application.
Follow this guide 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.
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. 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.
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 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.migrated - Triggered when a connection is migrated to another connector; the payload entity carries
migrated_fromwith the sourceservice_id. Emitted alongsidevault.connection.created(for the target connection) andvault.connection.deleted(for the source connection), all sharing the same request id. Migrated tokens…
Endpoints 37
Sessions
- POSTCreate Session
/vault/sessionsMaking 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…
Connections
- GETGet all connections
/vault/connections?api=crm&configured=trueThis endpoint includes all the configured integrations and contains the required assets to build an integrations page where your users can install… - GETGet connection
/vault/connections/:unified_api/:service_idGet a connection - POSTCreate connection
/vault/connections/:unified_api/:service_idCreate an authorized connection - DELETEDeletes a connection
/vault/connections/:unified_api/:service_idDeletes a connection - PATCHUpdate connection
/vault/connections/:unified_api/:service_idUpdate a connection - POSTImport connection
/vault/connections/:unified_api/:service_id/importImport an authorized connection. - POSTMigrate connection
/vault/connections/:unified_api/:service_id/migrateMigrate the connection to the target connector, keeping its credentials and connection state (settings, metadata, configuration, subscriptions, consents). The… - POSTAuthorize Access Token
/vault/connections/:unified_api/:service_id/tokenTriggers exchanging persisted connection credentials for an access token and store it in Vault. Currently supported for connections with the… - POSTValidate Connection State
/vault/connections/:unified_api/:service_id/validateThis endpoint validates the current state of a given connection. This will perform different checks based on the connection auth type. For basic and apiKey… - GETGet consent records
/vault/connections/:unified_api/:service_id/consentGet all consent records for a connection - PATCHUpdate consent state
/vault/connections/:unified_api/:service_id/consentUpdate the consent state of a connection - POSTConfirm Connection
/vault/connections/:unified_api/:service_id/confirmConfirms an OAuth connection after the callback by redeeming its confirm token. The confirm step is required when your application's OAuth protection mode was… - POSTCreate Callback State
/vault/connections/:unified_api/:service_id/callback-stateThis endpoint creates a callback state that can be used to issue requests to the callback endpoint. Call it with your API key. For an application with… - GETGet resource settings
/vault/connections/:unified_api/:service_id/:resource/configThis endpoint returns custom settings and their defaults required by connection for a given resource. - PATCHUpdate settings
/vault/connections/:unified_api/:service_id/:resource/configUpdate default values for a connection's resource settings - GETGet resource schema
/vault/connections/:unified_api/:service_id/:resource/schemaThis endpoint returns an approximate JSONSchema of a given resource. - GETGet resource example
/vault/connections/:unified_api/:service_id/:resource/exampleThis endpoint returns a downstream example of a given resource. - GETGet resource custom fields
/vault/connections/:unified_api/:service_id/:resource/custom-fields?resource_id=1234This endpoint returns an custom fields on a connection resource. - GETList connection custom mappings
/vault/connections/:unified_api/:service_id/:resource/custom-mappings?resource_id=1234This endpoint returns a list of custom mappings for a connection. - GETAuthorize
/vault/authorize/:service_id/:application_id?state=<jwt_token>&redirect_uri=http://example.com/integrations&scope=openid,leads:write,profile:read&nonce=a1b2c3d4-e5f6-7890-abcd-ef1234567890&opener_origin=https://app.example.com&embed_origin=https://portal.example.com__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… - GETRevoke connection
/vault/revoke/:service_id/:application_id?state=<jwt_token>&redirect_uri=http://example.com/integrations__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… - GETCallback
/vault/callback?state=<jwt_token>&code=g0ZGZmNjVmOWI&error=access_denied&error_description=The user denied access to your applicationThis 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… - GETProvider disconnect callback
/vault/oauth/disconnect/:jwt/:service_idEndpoint that receives browser redirect notifications from downstream providers when a user disconnects their OAuth integration. The JWT in the path encodes… - POSTProvider disconnect server callback
/vault/oauth/disconnect/:jwt/:service_idEndpoint that receives server-to-server POST callbacks from downstream providers when a user disconnects their OAuth integration. The JWT in the path encodes…
Consumers
- GETGet all consumers
/vault/consumers?filter={"consumer_id":"test-consumer","search":"john"}&cursor=string&limit=20This endpoint includes all application consumers, along with an aggregated count of requests made. - POSTCreate consumer
/vault/consumersCreate a consumer - GETGet consumer
/vault/consumers/:consumer_idConsumer detail including their aggregated counts with the connections they have authorized. - DELETEDelete consumer
/vault/consumers/:consumer_idDelete consumer and all their connections, including credentials. - PATCHUpdate consumer
/vault/consumers/:consumer_idUpdate consumer metadata such as name and email. - GETConsumer request counts
/vault/consumers/:consumer_id/stats?start_datetime=2021-05-01T12:00:00.000Z&end_datetime=2021-05-30T12:00:00.000ZGet consumer request counts within a given datetime range.
Logs
- GETGet all consumer request logs
/vault/logs?filter={"connector_id":"crm+salesforce","path":"/crm/contacts","path_match_mode":"CONTAINS","http_method":"GET","http_methods":["GET","POST"],"start_date":"2024-01-01T00:00:00.000Z","end_date":"2024-01-31T23:59:59.999Z","status_code":201,"status_codes":[200,201,204],"exclude_unified_apis":"vault,proxy"}&cursor=string&limit=20This endpoint includes all consumer request logs.
Custom Mappings
- GETGet custom mapping
/vault/custom-mappings/:unified_api/:service_id/:target_field_idGet a custom mapping - POSTCreate custom mapping
/vault/custom-mappings/:unified_api/:service_id/:target_field_idCreate a custom mapping - DELETEDeletes a custom mapping
/vault/custom-mappings/:unified_api/:service_id/:target_field_idDeletes a custom mapping - PATCHUpdate custom mapping
/vault/custom-mappings/:unified_api/:service_id/:target_field_idUpdate a custom mapping - GETList custom mappings
/vault/custom-mappings/:unified_api/:service_idThis endpoint returns a list of custom mappings.
API details
- Base URL
https://unify.apideck.com- Authentication
- An API key in the Authorization header
An API key in the x-apideck-app-id header - Operations
- 37 operations on 25 pathsGET 18POST 11PATCH 5DELETE 3
- Main resources
- Connections 24Consumers 6Custom Mappings 5Logs 1Sessions 1
- Response formats
application/jsontext/html- Description format
- OpenAPI 3.0.3, API version
10.83.0 - Links
- Documentation · OpenAPI document · Support
How to test the Vault API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Vault API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Create Session” (POST /vault/sessions), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Vault API?
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… It is listed under Developer tools and has 37 endpoints.
Who publishes the Vault API?
It is listed from Apideck's public API description (an OpenAPI document), not published by Apideck on Swastik Codes. Anyone who controls apideck.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Vault API?
Requests go to https://unify.apideck.com. Endpoint paths are added to this base URL.
How do I authenticate with the Vault API?
It accepts 2 methods: an API key in the Authorization header; an API key in the x-apideck-app-id header.
How many endpoints does the Vault API have?
37 operations on 25 paths (18 GET, 11 POST, 5 PATCH, 3 DELETE). The largest groups are Connections, Consumers, Custom Mappings, Logs.
Is forking the Vault API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.