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

Vault API

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

consumer_id

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

filter

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

resource

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

unified_api

x-apideck-app-id

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

x-apideck-consumer-id

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

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

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

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

Description

Indicates if the webhook has has been disabled as it reached its retry limit or if account is over the usage allocated by it's plan.

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)

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

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

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.

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.

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?

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

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 use API you have to sign up and get your own API key. Unify API accounts have sandbox mode and live mode API keys. 
To change modes just use the appropriate key to get a live or test object. You can find your API keys on the unify settings of your Apideck app.
Your Apideck application_id can also be found 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-apideck-api-key>`
- Application id header: `x-apideck-app-id: <your-apideck-app-id>`

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).
- Soon, you can skip the previous step and use the Apideck sandbox credentials to get you started instead (upcoming)
- 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
- Use the [publishing guides](/app-listing-requirements) to get your integration listed across app marketplaces.

### 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
- Search for integrations (upcoming)
- Give integration suggestions based on provided metadata (email or website) when creating the session (upcoming)

To use Hosted Vault, you will need to first [**create a session**](https://developers.apideck.com/apis/vault/reference#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.

Example using curl:

```
curl -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" }}'
```

### Vault API

_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).

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

More information about the connection state can be found in the [Connection state](https://developers.apideck.com/guides/connection-states) guide.

## 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. |

## Guides

- [Get started with Apideck](https://developers.apideck.com/getting-started)
- [Get started with Vault](https://developers.apideck.com/guides/vault)
- [Authorize connection via Vault](https://developers.apideck.com/guides/authorize-connections)
- [Vault connection status](https://developers.apideck.com/guides/connection-states)
- [How to build an integrations UI with Vault](https://github.com/apideck-samples/integration-settings)


## 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 API, you can migrate the access tokens and accounts to Apideck Vault. 

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

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.

### How does Vault work for Apideck Ecosystem customers?

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.

### How to integrate Apideck Vault

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:

- Vault API
- Hosted Vault
- Vault Widget (JS, React, Vue)

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 types does Vault support?

We support all the common authentication types, including: API keys, OAuth, Basic auth, and more.

#### API keys

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.

#### OAuth 2.0

##### Authorization Code Grant Type Flow

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 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 below.

# Authentication

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.


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

Get an access token for a connection and store it in Vault. Currently only supported for connections with the client_credentials OAuth grant type.

Note that the access token will not be returned in the response. A 200 response code indicates a valid access token was stored on the connection.


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 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 includes all consumer request logs.


__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 in case this is missing the default redirect uri you have configured for your Unify application.


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

An idempotency key is a unique value generated to recognize subsequent retries/duplicates of the same request.

x-apideck-idempotency-key

Return a 200 status to indicate that the data was received successfully.

Event broadcast when a connection has been created.

Event broadcast when a connection has been deleted.

Event broadcast when a connection has been disabled.

Event broadcast when a connection has been revoked.

Event broadcast when a connection has been updated.

Event broadcast when a connection token refresh has failed.

Vault connectors