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

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

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.