Vault API Reference

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

Welcome to the Vault API 👋

Building integrations starts with handling user credentials and generating access tokens for the APIs you want to use.

When you're looking to connect to an API, the first step is authentication. Vault helps you store API keys and access tokens from customers.

The only thing you need to use the Unify APIs is the consumer id, and Vault will do the look-up in the background to perform the API call(s), adding an extra layer of protection to prevent access token leakage.

Easily import the Vault API into your favorite API tool by using the buttons below.

Why Apideck Vault

The Vault API allows you to build your own integrations UI, so your customers can activate and configure integrations.

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. This strategy gives you full control over the flow and look & feel of the integration experience.

Through the Unify dashboard, you can configure which connectors you want to support as integrations, and it also allows you to control which kinds of providers your application supports

Alternatively, you can use the Hosted Vault, a no-code solution.

Get Started

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

  • Create a free account.
  • Sign in to the Apideck Unify Dashboard.
  • Get your API key and the application ID.
  • Select and configure the integrations you want to make available to your users
  • Retrieve the client_id and client_secret for the integration you want to activate (Only needed for OAuth integrations). You can skip this step by using the Apideck sandbox credentials to get you started. (GUIDES per service coming soon)
  • 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 API

If you are building your integration settings UI manually, you can call the Vault API directly. The Vault API is for companies who want to completely whitelabel the in-app integrations overview and authentication experience. 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. This strategy gives you full control over the flow and look & feel of the integration experience. Through the Unify dashboard you can configure which connectors you want to support as integrations. and also allows you to control which kinds of providers your application supports.

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

Beware, this is strategy takes more time to implement and is more complex than the hosted vault strategy.

Hosted Vault

Hosted Vault is a simple no-code solution, so you don't need to build your own UI to handle the integration settings and authentication. It's a great way to explore Unify without needing to build an integrations overview to get started.

Hosted Vault - Integrations portal

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

  • Add a connection (for an integration)
  • Handle the OAuth flow
  • Configure connection settings per integration
  • Manage connections
  • Discover and propose integration options

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.

Base URL

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

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.

Authorization

You can interact with the API through the authorization methods below.

apiKey

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

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

applicationId

The ID of your Unify application

Security Scheme Type API Key
Header parameter name x-apideck-app-id

Connectors

A full list of what vendors require which auth flow:

Service Service ID Auth Type Status
ActiveCampaign activecampaign API Key
Albacross albacross None
Close close API Key
Copper copper API Key
Crisp crisp None
Drift drift None
Exact Online exact-online OAuth2
Freshsales freshsales API Key
GeoDynamics geodynamics-be API Key
Google Analytics google-analytics None
Google Tag Manager google-tag-manager None
HubSpot hubspot OAuth2
Intercom intercom OAuth2
Iubenda iubenda None
journy.io journy-io None
Livechat livechat None
Metomic metomic-io None
Microsoft Dynamics CRM microsoft-dynamics OAuth2
Pipedrive pipedrive OAuth2
Plivo plivo Basic Auth
QuickBooks quickbooks OAuth2
Salesflare salesflare API Key
Salesforce salesforce OAuth2
Securex securex OAuth2
Segment segment None
Shopify shopify OAuth2
Slack slack OAuth2
Teamleader teamleader OAuth2
Twilio twilio Basic Auth
Xero xero OAuth2
Zendesk Sell zendesk-sell OAuth2
Zoho CRM zoho-crm OAuth2

Sandbox (upcoming)

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.

Guides

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. (COMING SOON)

Can I use Vault in combination with existing integrations?

Yes, you can. The granularity of Unify allows 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 strategies to use API tokens from your customers:

  • Vault API
  • Hosted Vault
  • Apideck Ecosystem (COMING SOON)

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?

What auth strategies does Vault handle? We currently support two flows so your customers can activate an integration.

API keys

For Services supporting the API key strategy, you will need to provide an in-app form where users can configure their API keys provided by the integration service. You can also use the drop-in solution if you don't want your own integration settings overview.

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.

Sessions

Create Session

post/vault/sessions

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 30 minutes (TTL: 1800).

Authorizations:

Header parameters

x-apideck-consumer-idstring
required

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

x-apideck-app-idstring
required

The ID of your Unify application

Additional redirect uri and/or consumer metadata

Request body schema

application/json
redirect_uristring
consumer_metadataobject
themeobject

Responses

200Session created
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Request example

Payload

{
  "redirect_uri": "https://mysaas.com/dashboard",
  "consumer_metadata": {
    "account_name": "SpaceX",
    "user_name": "Elon Musk",
    "image": "https://www.spacex.com/static/images/share.jpg"
  },
  "theme": {
    "vault_name": "Intercom",
    "primary_color": "#286efa",
    "sidepanel_background_color": "#286efa",
    "sidepanel_text_color": "#FFFFFF",
    "favicon": "https://www.intercom.com/_next/static/images/favicon-348ad8df6c167d93fb894e8bcb4dcd2a.png",
    "terms_url": "https://www.termsfeed.com/terms-conditions/957c85c1b089ae9e3219c83eff65377e",
    "privacy_url": "https://compliance.apideck.com/privacy-policy"
  }
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "data": {
      "session_uri": "http://vault.apideck.com/session/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zdW1lcl9pZCI6InRlc3RfdXNlcl9pZCIsImFwcGxpY2F0aW9uX2lkIj"
    }
  }
}

Connections

Get all connections

get/vault/connections

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.

Authorizations:

Query parameters

apistring

Scope results to Unified API

configuredboolean

Scopes results to connections that have been configured or not

Header parameters

x-apideck-consumer-idstring
required

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

x-apideck-app-idstring
required

The ID of your Unify application

Responses

200All Connections
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": [
    {
      "id": "lead+close",
      "service_id": "salesforce",
      "name": "Salesforce",
      "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
      "unified_api": "crm",
      "website": "https://www.salesforce.com",
      "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
      "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
      "api_key": "820b4ce9-b66d-4d12-9562-c859f2a6bf39",
      "settings": {
        "instance_url": "https://eu28.salesforce.com",
        "<setting-key>": "<setting-value>"
      },
      "metadata": {
        "ecosystem": {
          "name": "My Ecosystem",
          "id": "a6469332-7948-46a6-abc2-87ba3f005025"
        },
        "account": {
          "name": "My Company",
          "id": "c01458a5-7276-41ce-bc19-639906b0450a"
        }
      },
      "auth_type": "oauth2",
      "status": "live",
      "form_fields": [
        {
          "id": "instance_url",
          "label": "Instance url",
          "value": "https://eu28.salesforce.com",
          "placeholder": "",
          "mask": false,
          "type": "text",
          "required": true,
          "disabled": false,
          "custom_field": false
        }
      ],
      "configuration": [
        {
          "resource": "leads",
          "defaults": [
            {
              "id": "ProductInterest",
              "value": "GC5000 series"
            }
          ]
        }
      ],
      "configurable_resources": [
        "opportunities",
        "companies",
        "contacts",
        "leads"
      ],
      "settings_required_for_authorization": [
        "instance_url"
      ],
      "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
      "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
      "added": true,
      "enabled": true,
      "created_at": 1615563533390,
      "updated_at": 1616662325753,
      "state": "authorized"
    }
  ]
}

Update a connection

patch/vault/connections/{unified_api}/{service_id}

Update a connection

Authorizations:

Path parameters

service_idstring
required

Service ID of the resource to return

unified_apistring
required

Unified API

Header parameters

x-apideck-consumer-idstring
required

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

x-apideck-app-idstring
required

The ID of your Unify application

Fields to be updated on the resource

Request body schema

application/json
enabledboolean
api_keystring
Nullable

API Key. Only valid when auth_type is apiKey. OAuth connections do not require api_key.

settingsobject
Nullable

Connection settings. Values will persist to form_fields with corresponding id

metadataobject
Nullable

Responses

200Connection updated
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Request example

Payload

{
  "enabled": true,
  "api_key": "820b4ce9-b66d-4d12-9562-c859f2a6bf39",
  "settings": {
    "instance_url": "https://eu28.salesforce.com",
    "<setting-key>": "<setting-value>"
  },
  "metadata": {
    "ecosystem": {
      "name": "My Ecosystem",
      "id": "a6469332-7948-46a6-abc2-87ba3f005025"
    },
    "account": {
      "name": "My Company",
      "id": "c01458a5-7276-41ce-bc19-639906b0450a"
    }
  }
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "lead+close",
    "service_id": "salesforce",
    "name": "Salesforce",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "unified_api": "crm",
    "website": "https://www.salesforce.com",
    "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
    "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
    "api_key": "820b4ce9-b66d-4d12-9562-c859f2a6bf39",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "<setting-key>": "<setting-value>"
    },
    "metadata": {
      "ecosystem": {
        "name": "My Ecosystem",
        "id": "a6469332-7948-46a6-abc2-87ba3f005025"
      },
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      }
    },
    "auth_type": "oauth2",
    "status": "live",
    "form_fields": [
      {
        "id": "instance_url",
        "label": "Instance url",
        "value": "https://eu28.salesforce.com",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "id": "ProductInterest",
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
    "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
    "added": true,
    "enabled": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753,
    "state": "authorized"
  }
}

Deletes a connection

delete/vault/connections/{unified_api}/{service_id}

Deletes a connection

Authorizations:

Path parameters

service_idstring
required

Service ID of the resource to return

unified_apistring
required

Unified API

Header parameters

x-apideck-consumer-idstring
required

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

x-apideck-app-idstring
required

The ID of your Unify application

Responses

204Resource deleted
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 400,
  "error": "Bad Request",
  "typeName": "MissingHeadersError",
  "message": "Invalid Params",
  "detail": {
    "missing": [
      [
        {
          "foobar": "required"
        }
      ]
    ]
  },
  "ref": "https://developers.apideck.com/errors#missingheaderserror"
}

Connection Settings

get/vault/connections/{unified_api}/{service_id}/{resource}/config

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

Authorizations:

Path parameters

unified_apistring
required

Unified API

service_idstring
required

Service ID of the resource to return

resourcestring
required

Resource Name

Header parameters

x-apideck-consumer-idstring
required

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

x-apideck-app-idstring
required

The ID of your Unify application

Responses

200Connection
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "data": {
      "id": "lead+close",
      "service_id": "salesforce",
      "name": "Salesforce",
      "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
      "unified_api": "crm",
      "website": "https://www.salesforce.com",
      "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
      "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
      "api_key": "820b4ce9-b66d-4d12-9562-c859f2a6bf39",
      "settings": {
        "instance_url": "https://eu28.salesforce.com",
        "<setting-key>": "<setting-value>"
      },
      "metadata": {
        "ecosystem": {
          "name": "My Ecosystem",
          "id": "a6469332-7948-46a6-abc2-87ba3f005025"
        },
        "account": {
          "name": "My Company",
          "id": "c01458a5-7276-41ce-bc19-639906b0450a"
        }
      },
      "auth_type": "oauth2",
      "status": "live",
      "form_fields": [
        {
          "id": "instance_url",
          "label": "Instance url",
          "value": "https://eu28.salesforce.com",
          "placeholder": "",
          "mask": false,
          "type": "text",
          "required": true,
          "disabled": false,
          "custom_field": false
        }
      ],
      "configuration": [
        {
          "resource": "leads",
          "defaults": [
            {
              "id": "ProductInterest",
              "value": "GC5000 series"
            }
          ]
        }
      ],
      "configurable_resources": [
        "opportunities",
        "companies",
        "contacts",
        "leads"
      ],
      "settings_required_for_authorization": [
        "instance_url"
      ],
      "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
      "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
      "added": true,
      "enabled": true,
      "created_at": 1615563533390,
      "updated_at": 1616662325753,
      "state": "authorized"
    }
  }
}

Update Connection

patch/vault/connections/{unified_api}/{service_id}/{resource}/config

Update default values for a connection's resource settings

Authorizations:

Path parameters

service_idstring
required

Service ID of the resource to return

unified_apistring
required

Unified API

resourcestring
required

Resource Name

Header parameters

x-apideck-consumer-idstring
required

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

x-apideck-app-idstring
required

The ID of your Unify application

Fields that need to be updated on the resource

Request body schema

application/json
idstring
service_idstring
namestring
tag_linestring
unified_apistring
websitestring
iconstring
logostring
api_keystring
Nullable

API Key. Only valid when auth_type is apiKey. OAuth connections do not require api_key.

settingsobject
Nullable

Connection settings. Values will persist to form_fields with corresponding id

metadataobject
Nullable
auth_typestring
Nullable
Enum:oauth2apiKeybasic
statusstring
Enum:liveupcomingrequested
form_fieldsobjects
configurationobjects
configurable_resourcesstrings
settings_required_for_authorizationstrings
authorize_urlstring
revoke_urlstring
Nullable
addedboolean
enabledboolean
created_atnumber
updated_atnumber
statestring
Enum:availablecallableaddedconfiguredauthorized

Responses

200Connection updated
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Request example

Payload

{
  "service_id": "salesforce",
  "name": "Salesforce",
  "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
  "unified_api": "crm",
  "website": "https://www.salesforce.com",
  "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
  "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
  "api_key": "820b4ce9-b66d-4d12-9562-c859f2a6bf39",
  "settings": {
    "instance_url": "https://eu28.salesforce.com",
    "<setting-key>": "<setting-value>"
  },
  "metadata": {
    "ecosystem": {
      "name": "My Ecosystem",
      "id": "a6469332-7948-46a6-abc2-87ba3f005025"
    },
    "account": {
      "name": "My Company",
      "id": "c01458a5-7276-41ce-bc19-639906b0450a"
    }
  },
  "auth_type": "oauth2",
  "status": "live",
  "form_fields": [
    {
      "id": "instance_url",
      "label": "Instance url",
      "value": "https://eu28.salesforce.com",
      "placeholder": "",
      "mask": false,
      "type": "text",
      "required": true,
      "disabled": false,
      "custom_field": false
    }
  ],
  "configuration": [
    {
      "resource": "leads",
      "defaults": [
        {
          "id": "ProductInterest",
          "value": "GC5000 series"
        }
      ]
    }
  ],
  "configurable_resources": [
    "opportunities",
    "companies",
    "contacts",
    "leads"
  ],
  "settings_required_for_authorization": [
    "instance_url"
  ],
  "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
  "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
  "added": true,
  "enabled": true,
  "created_at": 1615563533390,
  "updated_at": 1616662325753,
  "state": "authorized"
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "lead+close",
    "service_id": "salesforce",
    "name": "Salesforce",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "unified_api": "crm",
    "website": "https://www.salesforce.com",
    "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
    "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
    "api_key": "820b4ce9-b66d-4d12-9562-c859f2a6bf39",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "<setting-key>": "<setting-value>"
    },
    "metadata": {
      "ecosystem": {
        "name": "My Ecosystem",
        "id": "a6469332-7948-46a6-abc2-87ba3f005025"
      },
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      }
    },
    "auth_type": "oauth2",
    "status": "live",
    "form_fields": [
      {
        "id": "instance_url",
        "label": "Instance url",
        "value": "https://eu28.salesforce.com",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "id": "ProductInterest",
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
    "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
    "added": true,
    "enabled": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753,
    "state": "authorized"
  }
}

Authorize

get/vault/authorize/{service_id}/{application_id}

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

Authorizations:

Path parameters

service_idstring
required

Service ID of the resource to return

application_idstring
required

Application ID of the resource to return

Query parameters

statestring
required

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.

redirect_uristring
required

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

scopestrings

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.

Responses

200ok
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 400,
  "error": "Bad Request",
  "typeName": "MissingHeadersError",
  "message": "Invalid Params",
  "detail": {
    "missing": [
      [
        {
          "foobar": "required"
        }
      ]
    ]
  },
  "ref": "https://developers.apideck.com/errors#missingheaderserror"
}

Revoke

get/vault/revoke/{service_id}/{application_id}

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

Authorizations:

Path parameters

service_idstring
required

Service ID of the resource to return

application_idstring
required

Application ID of the resource to return

Query parameters

statestring
required

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.

redirect_uristring
required

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

Responses

200ok
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 400,
  "error": "Bad Request",
  "typeName": "MissingHeadersError",
  "message": "Invalid Params",
  "detail": {
    "missing": [
      [
        {
          "foobar": "required"
        }
      ]
    ]
  },
  "ref": "https://developers.apideck.com/errors#missingheaderserror"
}

Proxy

Proxy call

post/vault/proxy

Proxies a downstream API call to a connector and injects the necessary credentials into a request stored in Vault. This allows you to have an additional security layer and logging without needing to rely on Unify for normalization. Note: Vault will proxy all data to the downstream URL and method/verb in the headers.

Authorizations:

Header parameters

x-apideck-consumer-idstring
required

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

x-apideck-app-idstring
required

The ID of your Unify application

x-apideck-service-idstring
required

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

x-apideck-downstream-authorizationstring

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

x-apideck-downstream-urlstring
required

Downstream URL

x-apideck-downstream-methodstring

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

Depending on the verb/method of the request this will contain the request body you want to POST/PATCH/PUT.

Request body schema

application/json

Responses

200Ok

Request example

Payload

{
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "2010-04-01",
  "body": "This is the ship that made the Kessel Run in fourteen parsecs?",
  "date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
  "date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
  "date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": "+15017122661",
  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": null,
  "sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "sent",
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
  },
  "to": "+15558675310",
  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
}

Response example

{}

Consumers

Get all consumers

get/vault/consumers

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

Authorizations:

Query parameters

cursorstring
Nullable

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

limitinteger[ 1 .. 200 ]
Default:20

Number of records to return

Header parameters

x-apideck-app-idstring
required

The ID of your Unify application

Responses

200All Consumers
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": [
    {
      "consumer_id": "test_consumer_id",
      "aggregated_request_count": 101,
      "request_counts": {
        "unify": 100,
        "proxy": 10,
        "vault": 21
      },
      "request_count_updated": "2021-05-07T12:55:42.242Z"
    }
  ],
  "meta": {
    "items_on_page": 50,
    "cursors": {
      "previous": "em9oby1jcm06OnBhZ2U6OjE=",
      "current": "em9oby1jcm06OnBhZ2U6OjI=",
      "next": "em9oby1jcm06OnBhZ2U6OjM="
    }
  },
  "links": {
    "previous": "https://unify.apideck.com/vault/consumers?cursor=em9oby1jcm06OnBhZ2U6OjE%3D",
    "current": "https://unify.apideck.com/vault/consumers",
    "next": "https://unify.apideck.com/vault/consumers?cursor=em9oby1jcm06OnBhZ2U6OjM"
  }
}

Get consumer

get/vault/consumers/{consumer_id}

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

Authorizations:

Path parameters

consumer_idstring
required

ID of the consumer to return

Header parameters

x-apideck-app-idstring
required

The ID of your Unify application

Responses

200Consumer
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "data": {
      "consumer_id": "test_consumer_id",
      "connections": [
        {
          "service_id": "teamleader",
          "unified_api": "crm",
          "state": "callable",
          "updated_at": 1616662325753
        }
      ],
      "aggregated_request_count": 101,
      "request_counts": {
        "unify": 100,
        "proxy": 10,
        "vault": 21
      },
      "request_count_updated": "2021-05-07T12:55:42.242Z"
    }
  }
}

Consumer request counts

get/vault/consumers/{consumer_id}/stats

Get consumer request counts within a given datetime range.

Authorizations:

Path parameters

consumer_idstring
required

ID of the consumer to return

Query parameters

start_datetimestring

Scopes results to requests that happened after datetime

end_datetimestring

Scopes results to requests that happened before datetime

Header parameters

x-apideck-app-idstring
required

The ID of your Unify application

Responses

200Consumers Request Counts within Date Range
400Bad Request
401Unauthorized
402Payment Required
404The specified resource was not found
422Unprocessable

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "application_id": "1111",
    "consumer_id": "test_user_id",
    "start_datetime": "2021-05-01T12:00:00.000Z",
    "end_datetime": "2021-05-10T12:00:00.000Z",
    "aggregated_request_count": 40,
    "request_counts": {
      "unify": 100,
      "proxy": 10,
      "vault": 21
    }
  }
}