Migrating Integrations

A common use case is that you already have pre-existing tokens from live integrations. The guide below explains how to migrate access tokens and credentials to Apideck to allow a seamless transition.

Import Connection

The import endpoint in our Vault API facilitates the import of a connection that was authorized outside of the Apideck product suite. This means that users who have authorization within your environment can be brought into Apideck along with their authorization.

Authorization

Similar to other calls to the Vault API, this endpoint requires the following headers:

x-apideck-app-id: [Your Unify Application ID]
x-apideck-consumer-id: [Your Consumer Identifie]
Authorization: 'Bearer [Your Unify Api Key]

Example:

POST: {{baseUrl}}/vault/connections/:unified_api/:service_id/import

{
  "credentials": {
    "access_token": "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..e6E6fFVEJTLKqeXjgiloMg.Cfxk4gm3Iab4DHw1PMLJZOhQdrbXiYwtCf2odk5vV4dNpqatHvq9MqtdSkjzM6Z1J3f0DYII3EpM3-dAPb1Vb0XfA9SKWkq329kxIHevMICzxDgUuXWMCYddatvZYyVJ62fBDVdjZBUxNxGDjLg9os0eCISRUFg4StFLmFfvuZE_1snjr1fu_gVvZA4sp4CiSvFi74LOAqadItrHkAfIYcs0Gca3IZQEZorerNB2AcJ73jDgT7pHxEhmun0GIOpienZ_j7C54uxUVOyJiWuJEvk5TWtzNmyTVoRj41ntBBZANo40fQcqvaDC9pFDXH1zJrNgRIIdZ_AdEJjvVKYAogOt7wUv_v1jI5vUpEOBczwJvzoSBT23vWnuzBcD1f4PsWaG2SpMkl4qS2nHZB0AsISuNVvf45O-cOLk2TK7E-M2fzxZTsTvqB_im9qQjJdonqQUols0_NmPaMJSLZdVHjHLz-m1Xaq1ebOQIlKb1qA654j--L3ov4dRa1SYhDHVO4kBy1hEqgnPcvW4Og2tIgWpFFS9b-Jx1OXzo4S4NQTdclzuY7RdYoEVlE5FX9MJU_DoGRpoz70cUKeW5mt2xaAD4EjTT0oFBuVb7TMRFSDPgcGAt2XllFTmQ12UhSJhIuS5fH9LjUartV4Ul5DzTjGp87r78YmCpd2VjjEal3aNvezvkWEdRfMt1fYzCc-EE0PI1o8Gx-B0D2sbgiaYuVmPgBByMQ_OufwyFUiQPepGV73WUGAMS6q5wJ2x4abV8kBTI-v1L1KjQt2Wf_9KIdFz3EF1SLdd6KVhb7Y6vClixHmDiQjKcneun08VReachmTpw_fbDSAByR80pq6Ik1LFIUWw08jJtrp2S27sdQSnqR8bVDG7L1vvQsN55dTD.E4FRbSEGpm7D_4c123456",
    "refresh_token": "AB11657526083yYu5cvT2ojgtzqWhwNQ1gu6VcfEACe123456",
    "issued_at": "2022-04-01T12:05:06.019Z",
    "expires_in": 3600000
  },
  "consumer_id": "test-consumer",
  "settings": {
    "realm_id": "4620816365164357123"
  },
  "metadata": {
    "account": "sandbox"
  }
}

Required:

One of either

credentials
or
settings
will contain properties reflecting the authorization. This is determined by the AuthType of the connection that is being imported.

If the connector has an authorization type of

AuthType.apiKey
or
AuthType.basic
, the settings property must include the appropriate configuration. (api_key or user/pass etc.) If the connector has an authorization type of
AuthType.oauth2
, the
credentials
property must contain an
access_token
and a
refresh_token
.

Refreshing Tokens

When importing an

AuthType.oauth2
connection, the
issued_at
and
expires_at
properties determine when the token will need to be refreshed. If the token is expired OR if these parameters are omitted, we will trigger a background job that will use the
refresh_token
to obtain a new
access_token
.

Webhooks

If the job that is attempting to refresh the access_token of an

AuthType.oauth2
connection fails, we publish a webhook event. This webhook contains non-sensitive information about the connection. If you wish to receive this webhook, it can be configured in the Apideck Admin under Unify -> Webhooks -> Vault API -> Event:
vault.connection.token_refresh.failed
.

Retry

When performing an import, the connection is upserted. If the connection already exists with id

application_id+consumer_id
, it will be updated, otherwise, a new connection is created.

⚠️ If you map an object that only contains a type, it will be removed.