The File Picker arrived!Build better SaaS onboarding through API-powered data imports.

Apideck Documentation Page
Search docs

Vault API Reference

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

8.29.4

Introduction

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

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

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.

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 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
  • 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 three flows so your customers can activate an integration.

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

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 API Key
Header parameter name Authorization

applicationId

The ID of your Unify application

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

Sessions

The Sessions model

consumer_metadataobject
custom_consumer_settingsobject

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

redirect_uristring
settingsobject
themeobject
Sessions example
{}

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 1 hour (TTL: 3600).

Authorizations:
apiKey

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
consumer_metadataobject
custom_consumer_settingsobject

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

redirect_uristring
settingsobject
themeobject

Responses

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

Request example

{
  "consumer_metadata": {
    "account_name": "SpaceX",
    "user_name": "Elon Musk",
    "email": "elon@musk.com",
    "image": "https://www.spacex.com/static/images/share.jpg"
  },
  "custom_consumer_settings": {
    "feature_flag_1": true,
    "tax_rates": [
      {
        "id": "6",
        "label": "6%"
      },
      {
        "id": "21",
        "label": "21%"
      }
    ]
  },
  "redirect_uri": "https://mysaas.com/dashboard",
  "settings": {
    "unified_apis": [
      "crm"
    ],
    "hide_resource_settings": false,
    "sandbox_mode": false,
    "isolation_mode": false,
    "session_length": "30m",
    "show_logs": true,
    "show_suggestions": false,
    "auto_redirect": false
  },
  "theme": {
    "favicon": "https://res.cloudinary.com/apideck/icons/intercom",
    "primary_color": "#286efa",
    "privacy_url": "https://compliance.apideck.com/privacy-policy",
    "sidepanel_background_color": "#286efa",
    "sidepanel_text_color": "#FFFFFF",
    "terms_url": "https://www.termsfeed.com/terms-conditions/957c85c1b089ae9e3219c83eff65377e",
    "vault_name": "Intercom"
  }
}

Response example

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

Connections

The Connections model

idstring
service_idstring
namestring
tag_linestring
unified_apistring
statestring
Enum:availablecallableaddedauthorized

Connection state flow

Connections example
{}

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:
apiKey

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

Query parameters

apistring

Scope results to Unified API

configuredboolean

Scopes results to connections that have been configured or not

Responses

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID',
  consumerId: 'REPLACE_WITH_CONSUMER_ID'
})

try {
  const { data } = await apideck.vault.connectionsAll({})
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": [
    {
      "id": "crm+salesforce",
      "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",
      "state": "authorized",
      "auth_type": "oauth2",
      "oauth_grant_type": "authorization_code",
      "status": "live",
      "enabled": true,
      "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",
      "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>",
      "settings": {
        "instance_url": "https://eu28.salesforce.com",
        "api_key": "12345xxxxxx"
      },
      "metadata": {
        "account": {
          "name": "My Company",
          "id": "c01458a5-7276-41ce-bc19-639906b0450a"
        },
        "plan": "enterprise"
      },
      "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,
          "sensitive": false
        },
        {
          "id": "api_key",
          "label": "API Key",
          "value": "123455677",
          "placeholder": "",
          "mask": false,
          "type": "text",
          "required": true,
          "disabled": false,
          "custom_field": false,
          "sensitive": true
        }
      ],
      "configuration": [
        {
          "resource": "leads",
          "defaults": [
            {
              "target": "custom_fields",
              "id": "ProductInterest",
              "options": [
                {
                  "label": "General Channel",
                  "value": "general"
                }
              ],
              "value": "GC5000 series"
            }
          ]
        }
      ],
      "configurable_resources": [
        "opportunities",
        "companies",
        "contacts",
        "leads"
      ],
      "resource_schema_support": [
        "leads"
      ],
      "resource_settings_support": [
        "leads"
      ],
      "settings_required_for_authorization": [
        "instance_url"
      ],
      "has_guide": true,
      "created_at": 1615563533390,
      "updated_at": 1616662325753
    }
  ]
}

Get connection

get/vault/connections/{unified_api}/{se...

Get a connection

Authorizations:
apiKey

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

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID',
  consumerId: 'REPLACE_WITH_CONSUMER_ID'
})

try {
  const { data } = await apideck.vault.connectionsOne({
    serviceId: 'pipedrive',
    unifiedApi: 'crm'
  })
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "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",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "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",
    "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>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "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,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "has_guide": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}

Create connection

post/vault/connections/{unified_api}/{se...

Create an authorized connection

Authorizations:
apiKey

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 that need to be persisted on the resource

Request body schema

application/json
enabledboolean

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

settingsobject or null

Connection settings. Values will persist to form_fields with corresponding id

metadataobject or null

Attach your own consumer specific metadata

configurationobjects

Responses

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

Request example

{
  "enabled": true,
  "settings": {
    "instance_url": "https://eu28.salesforce.com",
    "api_key": "12345xxxxxx"
  },
  "metadata": {
    "account": {
      "name": "My Company",
      "id": "c01458a5-7276-41ce-bc19-639906b0450a"
    },
    "plan": "enterprise"
  },
  "configuration": [
    {
      "resource": "leads",
      "defaults": [
        {
          "id": "ProductInterest",
          "options": [
            {
              "label": "General Channel",
              "value": "general"
            }
          ],
          "value": "GC5000 series"
        }
      ]
    }
  ]
}

Response example

{
  "status_code": 201,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "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",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "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",
    "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>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "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,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "has_guide": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}

Update connection

patch/vault/connections/{unified_api}/{se...

Update a connection

Authorizations:
apiKey

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 that need to be updated on the resource

Request body schema

application/json
enabledboolean

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

settingsobject or null

Connection settings. Values will persist to form_fields with corresponding id

metadataobject or null

Attach your own consumer specific metadata

configurationobjects

Responses

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

Request example

{
  "enabled": true,
  "settings": {
    "instance_url": "https://eu28.salesforce.com",
    "api_key": "12345xxxxxx"
  },
  "metadata": {
    "account": {
      "name": "My Company",
      "id": "c01458a5-7276-41ce-bc19-639906b0450a"
    },
    "plan": "enterprise"
  },
  "configuration": [
    {
      "resource": "leads",
      "defaults": [
        {
          "id": "ProductInterest",
          "options": [
            {
              "label": "General Channel",
              "value": "general"
            }
          ],
          "value": "GC5000 series"
        }
      ]
    }
  ]
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "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",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "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",
    "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>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "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,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "has_guide": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}

Deletes a connection

delete/vault/connections/{unified_api}/{se...

Deletes a connection

Authorizations:
apiKey

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID',
  consumerId: 'REPLACE_WITH_CONSUMER_ID'
})

try {
  const { data } = await apideck.vault.connectionsDelete({
    serviceId: 'pipedrive',
    unifiedApi: 'crm'
  })
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 400,
  "error": "Bad Request",
  "type_name": "RequestValidationError",
  "message": "Invalid Params",
  "detail": "Missing property foobar",
  "ref": "https://developers.apideck.com/errors#requestvalidationerror"
}

Import connection

post/vault/connections/{unified_api}/{se...

Import an authorized connection.

Authorizations:
apiKey

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 that need to be persisted on the resource

Request body schema

application/json
credentialsobject
settingsobject or null

Connection settings. Values will persist to form_fields with corresponding id

metadataobject or null

Attach your own consumer specific metadata

Responses

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

Request example

{
  "credentials": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.cThIIoDvwdueQB468K5xDc5633seEFoqwxjF_xSJyQQ"
  },
  "settings": {
    "instance_url": "https://eu28.salesforce.com"
  },
  "metadata": {
    "account": {
      "name": "My Company",
      "id": "c01458a5-7276-41ce-bc19-639906b0450a"
    },
    "plan": "enterprise"
  }
}

Response example

{
  "status_code": 201,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "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",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "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",
    "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>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "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,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "has_guide": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}

Get Access Token

post/vault/connections/{unified_api}/{se...

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.

Authorizations:
apiKey

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

Request body schema

application/json

Responses

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

Request example

{}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "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",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "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",
    "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>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "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,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "has_guide": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}

Get resource settings

get/vault/connections/{unified_api}/{se...

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

Authorizations:
apiKey

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID',
  consumerId: 'REPLACE_WITH_CONSUMER_ID'
})

const params = {
  unifiedApi: 'crm',
  serviceId: 'pipedrive',
  resource: 'leads'
}

try {
  const { data } = await apideck.vault.connectionsGetSettings(params)
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "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",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "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",
    "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>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "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,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "has_guide": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}

Update settings

patch/vault/connections/{unified_api}/{se...

Update default values for a connection's resource settings

Authorizations:
apiKey

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
enabledboolean

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

settingsobject or null

Connection settings. Values will persist to form_fields with corresponding id

metadataobject or null

Attach your own consumer specific metadata

configurationobjects

Responses

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

Request example

{
  "enabled": true,
  "settings": {
    "instance_url": "https://eu28.salesforce.com",
    "api_key": "12345xxxxxx"
  },
  "metadata": {
    "account": {
      "name": "My Company",
      "id": "c01458a5-7276-41ce-bc19-639906b0450a"
    },
    "plan": "enterprise"
  },
  "configuration": [
    {
      "resource": "leads",
      "defaults": [
        {
          "id": "ProductInterest",
          "options": [
            {
              "label": "General Channel",
              "value": "general"
            }
          ],
          "value": "GC5000 series"
        }
      ]
    }
  ]
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "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",
    "state": "authorized",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "status": "live",
    "enabled": true,
    "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",
    "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>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "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,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "instance_url"
    ],
    "has_guide": true,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}

Authorize

get/vault/authorize/{service_id}/{appli...

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.

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

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY'
})

const params = {
  serviceId: 'pipedrive',
  applicationId: 'application_id_example',
  state:
    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zdW1lcl9pZCI6InRlc3RfdXNlcl9pZCIsInVuaWZpZWRfYXBpIjoiZGVmYXVsdCIsInNlcnZpY2VfaWQiOiJ0ZWFtbGVhZGVyIiwiYXBwbGljYXRpb25faWQiOiIxMTExIiwiaWF0IjoxNjIyMTI2Nzg3fQ.97_pn1UAXc7mctXBdr15czUNO1jjdQ9sJUOIE_Myzbk',
  redirectUri: 'http://example.com/integrations'
}

try {
  const { data } = await apideck.vault.connectionsAuthorize(params)
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 400,
  "error": "Bad Request",
  "type_name": "RequestValidationError",
  "message": "Invalid Params",
  "detail": "Missing property foobar",
  "ref": "https://developers.apideck.com/errors#requestvalidationerror"
}

Revoke

get/vault/revoke/{service_id}/{applicat...

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.

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

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY'
})

const params = {
  serviceId: 'pipedrive',
  applicationId: 'application_id_example',
  state:
    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zdW1lcl9pZCI6InRlc3RfdXNlcl9pZCIsInVuaWZpZWRfYXBpIjoiZGVmYXVsdCIsInNlcnZpY2VfaWQiOiJ0ZWFtbGVhZGVyIiwiYXBwbGljYXRpb25faWQiOiIxMTExIiwiaWF0IjoxNjIyMTI2Nzg3fQ.97_pn1UAXc7mctXBdr15czUNO1jjdQ9sJUOIE_Myzbk',
  redirectUri: 'http://example.com/integrations'
}

try {
  const { data } = await apideck.vault.connectionsRevoke(params)
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 400,
  "error": "Bad Request",
  "type_name": "RequestValidationError",
  "message": "Invalid Params",
  "detail": "Missing property foobar",
  "ref": "https://developers.apideck.com/errors#requestvalidationerror"
}

Callback

get/vault/callback

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.

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.

codestring
required

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

Responses

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY'
})

const params = {
  state:
    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb25zdW1lcl9pZCI6InRlc3RfdXNlcl9pZCIsInVuaWZpZWRfYXBpIjoiZGVmYXVsdCIsInNlcnZpY2VfaWQiOiJ0ZWFtbGVhZGVyIiwiYXBwbGljYXRpb25faWQiOiIxMTExIiwiaWF0IjoxNjIyMTI2Nzg3fQ.97_pn1UAXc7mctXBdr15czUNO1jjdQ9sJUOIE_Myzbk',
  code: 'g0ZGZmNjVmOWI'
}

try {
  const { data } = await apideck.vault.connectionsCallback(params)
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 400,
  "error": "Bad Request",
  "type_name": "RequestValidationError",
  "message": "Invalid Params",
  "detail": "Missing property foobar",
  "ref": "https://developers.apideck.com/errors#requestvalidationerror"
}

Consumers

The Consumers model

consumer_idstring
application_idstring
metadataobject
connectionsobjects
servicesstrings
aggregated_request_countnumber
Consumers example
{}

Get all consumers

get/vault/consumers

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

Authorizations:
apiKey

Header parameters

x-apideck-app-idstring
required

The ID of your Unify application

Query parameters

cursorstring or null

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

Responses

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID'
})

try {
  const { data } = await apideck.vault.consumersAll({})
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": [
    {
      "consumer_id": "test_consumer_id",
      "application_id": "1111",
      "metadata": {
        "account_name": "SpaceX",
        "user_name": "Elon Musk",
        "email": "elon@musk.com",
        "image": "https://www.spacex.com/static/images/share.jpg"
      },
      "aggregated_request_count": 101,
      "request_counts": {
        "unify": 100,
        "proxy": 10,
        "vault": 21
      },
      "created": "2021-05-07T12:55:42.242Z",
      "modified": "2021-05-07T12:55:42.242Z",
      "request_count_updated": "2021-05-07T12:55:42.242Z",
      "services": [
        "salesforce",
        "stripe"
      ]
    }
  ]
}

Get consumer

get/vault/consumers/{consumer_id}

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

Authorizations:
apiKey

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID'
})

try {
  const { data } = await apideck.vault.consumersOne({
    consumerId: 'test_user_id'
  })
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": {
    "consumer_id": "test_consumer_id",
    "application_id": "1111",
    "metadata": {
      "account_name": "SpaceX",
      "user_name": "Elon Musk",
      "email": "elon@musk.com",
      "image": "https://www.spacex.com/static/images/share.jpg"
    },
    "connections": [
      {
        "id": "1111+test_user_id",
        "name": "Salesforce",
        "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",
        "website": "https://www.salesforce.com",
        "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
        "service_id": "teamleader",
        "unified_api": "crm",
        "consumer_id": "test_user_id",
        "auth_type": "oauth2",
        "enabled": true,
        "settings": {
          "instance_url": "https://eu28.salesforce.com"
        },
        "metadata": {
          "account": {
            "name": "My Company",
            "id": "c01458a5-7276-41ce-bc19-639906b0450a"
          },
          "plan": "enterprise"
        },
        "created_at": "2020-09-19T12:18:37.071Z",
        "updated_at": "2020-09-19T12:18:37.071Z",
        "state": "authorized"
      }
    ],
    "services": [
      "salesforce",
      "stripe"
    ],
    "aggregated_request_count": 101,
    "request_counts": {
      "unify": 100,
      "proxy": 10,
      "vault": 21
    },
    "created": "2021-05-07T12:55:42.242Z",
    "modified": "2021-05-07T12:55:42.242Z",
    "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:
apiKey

Path parameters

consumer_idstring
required

ID of the consumer to return

Header parameters

x-apideck-app-idstring
required

The ID of your Unify application

Query parameters

start_datetimestring
required

Scopes results to requests that happened after datetime

end_datetimestring
required

Scopes results to requests that happened before datetime

Responses

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID'
})

const params = {
  consumerId: 'test_user_id',
  startDatetime: '2021-05-01T12:00:00.000Z',
  endDatetime: '2021-05-30T12:00:00.000Z'
}

try {
  const { data } = await apideck.vault.consumersRequestCounts(params)
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

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

Logs

The Logs model

api_stylestring
required

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

base_urlstring
required

The Apideck base URL the request was made to.

child_requestboolean
required

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

consumer_idstring
required

The consumer Id associated with the request.

durationnumber
required

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

error_messagestring or null

If error occurred, this is brief explanation

Logs example
{}

Get all consumer request logs

get/vault/logs

This endpoint includes all consumer request logs.

Authorizations:
apiKey

Header parameters

x-apideck-app-idstring
required

The ID of your Unify application

x-apideck-consumer-idstring
required

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

Query parameters

filterobjectfilter[connector_id]=crm+salesforce

Filter results

cursorstring or null

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

Responses

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

Request example

Node
import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: 'REPLACE_WITH_API_KEY',
  appId: 'REPLACE_WITH_APP_ID',
  consumerId: 'REPLACE_WITH_CONSUMER_ID'
})

try {
  const { data } = await apideck.vault.logsAll({})
  console.log('API called successfully', data)
} catch (error) {
  console.error(error)
}

Response example

{
  "status_code": 200,
  "status": "OK",
  "data": [
    {
      "api_style": "REST",
      "base_url": "unify.apideck.com",
      "child_request": false,
      "consumer_id": "test-consumer",
      "duration": 2220.379304,
      "error_message": "Refresh token is invalid",
      "execution": 2248,
      "has_children": false,
      "http_method": "GET",
      "id": "0b5f7480-5550-4f5c-a5fc-3c01ac43dd0f",
      "latency": 27.620695999999953,
      "operation": {
        "id": "connectionsAll",
        "name": "Get All Connections"
      },
      "parent_id": "0b5f7480-5550-4f5c-a5fc-3c01ac43dd0f",
      "path": "/vault/connections",
      "sandbox": false,
      "service": {
        "id": "apideck-vault",
        "name": "Apideck Vault"
      },
      "source_ip": "94.227.131.238",
      "status_code": 200,
      "success": true,
      "timestamp": "2021-07-12T14:26:17.420Z",
      "unified_api": "vault"
    }
  ],
  "meta": {
    "items_on_page": 50,
    "cursors": {
      "previous": "em9oby1jcm06OnBhZ2U6OjE=",
      "current": "em9oby1jcm06OnBhZ2U6OjI=",
      "next": "em9oby1jcm06OnBhZ2U6OjM="
    }
  },
  "links": {
    "previous": "https://unify.apideck.com/crm/companies?cursor=em9oby1jcm06OnBhZ2U6OjE%3D",
    "current": "https://unify.apideck.com/crm/companies",
    "next": "https://unify.apideck.com/crm/companies?cursor=em9oby1jcm06OnBhZ2U6OjM"
  }
}

Webhook Events

Connection Updated
Webhook

postConnectionUpdated

Connection Updated

Authorizations:
apiKey
applicationId

Header parameters

x-apideck-event-typestring
required
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted

The type of event that was triggered

Request body schema

application/json
event_idstring

Unique reference to this request event

service_idstring

Service provider identifier

entity_idstring

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

entity_typestring

The type entity that triggered this event

entityobject
event_typestring
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted
execution_attemptnumber

The current count this request event has been attempted

occurred_atstring

ISO Datetime for when the original event occurred

Responses

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

Request example

Payload
{
  "event_id": "9755c355-56c3-4a2f-a2da-86ff4411fccb",
  "service_id": "close",
  "entity_id": "123456ASDF",
  "entity_type": "Company",
  "entity": {
    "id": "1111+test_user_id",
    "name": "Salesforce",
    "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",
    "website": "https://www.salesforce.com",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "service_id": "teamleader",
    "unified_api": "crm",
    "consumer_id": "test_user_id",
    "auth_type": "oauth2",
    "enabled": true,
    "settings": {
      "instance_url": "https://eu28.salesforce.com"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "created_at": "2020-09-19T12:18:37.071Z",
    "updated_at": "2020-09-19T12:18:37.071Z",
    "state": "authorized"
  },
  "event_type": "vault.connection.created",
  "execution_attempt": 2,
  "occurred_at": "2021-10-01T03:14:55.419Z"
}

Connection Created
Webhook

postConnectionCreated

Connection Created

Authorizations:
apiKey
applicationId

Header parameters

x-apideck-event-typestring
required
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted

The type of event that was triggered

Request body schema

application/json
event_idstring

Unique reference to this request event

service_idstring

Service provider identifier

entity_idstring

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

entity_typestring

The type entity that triggered this event

entityobject
event_typestring
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted
execution_attemptnumber

The current count this request event has been attempted

occurred_atstring

ISO Datetime for when the original event occurred

Responses

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

Request example

Payload
{
  "event_id": "9755c355-56c3-4a2f-a2da-86ff4411fccb",
  "service_id": "close",
  "entity_id": "123456ASDF",
  "entity_type": "Company",
  "entity": {
    "id": "1111+test_user_id",
    "name": "Salesforce",
    "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",
    "website": "https://www.salesforce.com",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "service_id": "teamleader",
    "unified_api": "crm",
    "consumer_id": "test_user_id",
    "auth_type": "oauth2",
    "enabled": true,
    "settings": {
      "instance_url": "https://eu28.salesforce.com"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "created_at": "2020-09-19T12:18:37.071Z",
    "updated_at": "2020-09-19T12:18:37.071Z",
    "state": "authorized"
  },
  "event_type": "vault.connection.created",
  "execution_attempt": 2,
  "occurred_at": "2021-10-01T03:14:55.419Z"
}

Connection Deleted
Webhook

postConnectionDeleted

Connection Deleted

Authorizations:
apiKey
applicationId

Header parameters

x-apideck-event-typestring
required
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted

The type of event that was triggered

Request body schema

application/json
event_idstring

Unique reference to this request event

service_idstring

Service provider identifier

entity_idstring

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

entity_typestring

The type entity that triggered this event

entityobject
event_typestring
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted
execution_attemptnumber

The current count this request event has been attempted

occurred_atstring

ISO Datetime for when the original event occurred

Responses

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

Request example

Payload
{
  "event_id": "9755c355-56c3-4a2f-a2da-86ff4411fccb",
  "service_id": "close",
  "entity_id": "123456ASDF",
  "entity_type": "Company",
  "entity": {
    "id": "1111+test_user_id",
    "name": "Salesforce",
    "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",
    "website": "https://www.salesforce.com",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "service_id": "teamleader",
    "unified_api": "crm",
    "consumer_id": "test_user_id",
    "auth_type": "oauth2",
    "enabled": true,
    "settings": {
      "instance_url": "https://eu28.salesforce.com"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "created_at": "2020-09-19T12:18:37.071Z",
    "updated_at": "2020-09-19T12:18:37.071Z",
    "state": "authorized"
  },
  "event_type": "vault.connection.created",
  "execution_attempt": 2,
  "occurred_at": "2021-10-01T03:14:55.419Z"
}

Connection Callable
Webhook

postConnectionCallable

Connection Callable

Authorizations:
apiKey
applicationId

Header parameters

x-apideck-event-typestring
required
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted

The type of event that was triggered

Request body schema

application/json
event_idstring

Unique reference to this request event

service_idstring

Service provider identifier

entity_idstring

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

entity_typestring

The type entity that triggered this event

entityobject
event_typestring
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted
execution_attemptnumber

The current count this request event has been attempted

occurred_atstring

ISO Datetime for when the original event occurred

Responses

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

Request example

Payload
{
  "event_id": "9755c355-56c3-4a2f-a2da-86ff4411fccb",
  "service_id": "close",
  "entity_id": "123456ASDF",
  "entity_type": "Company",
  "entity": {
    "id": "1111+test_user_id",
    "name": "Salesforce",
    "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",
    "website": "https://www.salesforce.com",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "service_id": "teamleader",
    "unified_api": "crm",
    "consumer_id": "test_user_id",
    "auth_type": "oauth2",
    "enabled": true,
    "settings": {
      "instance_url": "https://eu28.salesforce.com"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "created_at": "2020-09-19T12:18:37.071Z",
    "updated_at": "2020-09-19T12:18:37.071Z",
    "state": "authorized"
  },
  "event_type": "vault.connection.created",
  "execution_attempt": 2,
  "occurred_at": "2021-10-01T03:14:55.419Z"
}

Token Refresh Failed
Webhook

postTokenRefreshFailed

Attempt to refresh the connections access_token failed.

Authorizations:
apiKey
applicationId

Header parameters

x-apideck-event-typestring
required
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted

The type of event that was triggered

Request body schema

application/json
event_idstring

Unique reference to this request event

service_idstring

Service provider identifier

entity_idstring

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

entity_typestring

The type entity that triggered this event

entityobject
event_typestring
Enum:*vault.connection.createdvault.connection.updatedvault.connection.deleted
execution_attemptnumber

The current count this request event has been attempted

occurred_atstring

ISO Datetime for when the original event occurred

Responses

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

Request example

Payload
{
  "event_id": "9755c355-56c3-4a2f-a2da-86ff4411fccb",
  "service_id": "close",
  "entity_id": "123456ASDF",
  "entity_type": "Company",
  "entity": {
    "id": "1111+test_user_id",
    "name": "Salesforce",
    "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",
    "website": "https://www.salesforce.com",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "service_id": "teamleader",
    "unified_api": "crm",
    "consumer_id": "test_user_id",
    "auth_type": "oauth2",
    "enabled": true,
    "settings": {
      "instance_url": "https://eu28.salesforce.com"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "created_at": "2020-09-19T12:18:37.071Z",
    "updated_at": "2020-09-19T12:18:37.071Z",
    "state": "authorized"
  },
  "event_type": "vault.connection.created",
  "execution_attempt": 2,
  "occurred_at": "2021-10-01T03:14:55.419Z"
}