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.