# 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](/apis/vault/reference#operation/connectionsImport) 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.