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).
The base URL for all API requests is https://unify.apideck.com
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.
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:
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.
Example using curl:
Docs
Main site
Need help?
Participate
Resourcescurl -X POST https://unify.apideck.com/vault/sessions
-H "Content-Type: application/json"
-H "Authorization: Bearer <your-api-key>"
-H "X-APIDECK-CONSUMER-ID: <consumer-id>"
-H "X-APIDECK-APP-ID: <application-id>"
-d '{"consumer_metadata": { "account_name" : "Sample", "user_name": "Sand Box", "email": "sand@box.com", "image": "https://unavatar.now.sh/jake" }, "theme": { "vault_name": "Intercom", "primary_color": "#286efa", "sidepanel_background_color": "#286efa","sidepanel_text_color": "#FFFFFF", "favicon": "https://res.cloudinary.com/apideck/icons/intercom" }}'
Beware, this is strategy takes more time to implement in comparison to 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 (upcoming).
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.
The connection state is computed based on the connection flow below.
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).
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. |
The sandbox is pre-loaded with data similar to a real-life integrations setup. You can use the preconfigured OAauth configured connectors for testing purposes and can skip this step by using the Apideck sandbox credentials to get you started.
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.
Vault employs data minimization, therefore only requesting the minimum amount of scopes needed to perform an API request.
Using our migration API, you can migrate the access tokens and accounts to Apideck Vault. (COMING SOON)
Yes, you can. The flexibility of Unify allows you to quickly the use cases you need while keeping a gradual migration path based on your timeline and requirements.
Once logged in, pick your ecosystem; on the left-hand side of the screen, you’ll have the option to create an application underneath the Unify section.
This section covers everything you need to know to authenticate your customers through Vault. Vault provides three auth strategies to use API tokens from your customers:
You can also opt to bypass Vault and still take care of authentication flows yourself. Make sure to put the right safeguards in place to protect your customers’ tokens and other sensitive data.
What auth strategies does Vault handle? We currently support three flows so your customers can activate an integration.
For Services supporting the API key strategy, you can use Hosted Vault will need to provide an in-app form where users can configure their API keys provided by the integration service.
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 being handled by the /authorize endpoint.
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 below.
Use this page to mock Vault API in your testing and development.
Run our mock API sample using the open source WireMock library, or in the free edition of WireMock Cloud. You'll have a working API server simulating the behavior of Vault API, which will allow you to keep building and testing even if the actual API you isn't currently available.
