---
title: "Link a v2 app to a v3 app"
method: POST
path: "/v3/migration-tools/link-v2v3-apps"
tags: ["App migration"]
---

# Link a v2 app to a v3 app

`POST /v3/migration-tools/link-v2v3-apps`

Link an existing v2 application to an existing v3 application.

<div id="admonition-warning">⚠️<strong>Your v2 and v3 applications must be in the same data center region to use these tools. </strong> You can only use these tools to migrate a v2 application to a v3 application in the same region. You cannot use these to move a v2 application to a different region.</div>

This is the first step of the migration process, and is how you tell Nylas which v2 application you are migrating.

To use this API you need the v2 source application ID and secret, in the format you use to authorize v2 API calls, and the v3 API key from the v3 destination application.

To verify that you own the v2 source application you're linking, add the `BasicV2` API header. This extra header is required. The `BasicV2` API header contains a Base64-encoded `V2_APP_ID:V2_APP_SECRET`, which is also used for Basic auth for any v2 API call.

```bash
--header 'BasicV2: <base64-encoded V2_APP_ID:V2_APP_SECRET> // Use the -n flag when you Base64 encode
```

No further request body is required. Nylas detects the v3 application ID from the API key, and the v2 application ID from the BasicV2 header.

The API is rate limited to 20 requests per second per Nylas application ID.

## Response `200`

On success, returns the existing v3 application object with added linked v2 application ID.

- object
  - `request_id` string — The request ID.
  - `data` ApplicationObject
    - `application_id` string — Application ID
    - `organization_id` string — ID of organization
    - `region` string — Region identifier
    - `environment` 'production' | 'staging' — Environment identifier
    - `default_workspace_id` string — The ID of the application's default [workspace](/docs/reference/api/workspaces/), if one exists. Nylas manages this value, and ignores it in create and update requests.
    - `v2_application_id` string — Linked v2 Application ID
    - `branding` object
      - `name` string — Name of the application
      - `icon_url` string — URL points to application icon.
      - `website_url` string — Application / publisher website URL
      - `description` string — Description of the application.
    - `hosted_authentication` object
      - `background_image_url` string — URL of the background image
      - `alignment` 'left' | 'center' | 'right' — Alignment of background image
      - `color_primary` string — Primary color
      - `color_secondary` string — Secondary color
      - `title` string — Title
      - `subtitle` string — Subtitle
      - `background_color` string — Background color
      - `spacing` integer — CSS spacing attribute in px
    - `callback_uris` union[] — A list of your application's callback URIs.
      - union
        - WebDesktopCallbackNoSettings
          - `platform` 'web' | 'desktop' — Platform identifier
          - `id` string — The callback URI ID. This must be a universally unique ID (UUID).
          - `url` string — Your project's callback URI, including the protocol. Nylas accepts HTTP for localhost development _only_. Otherwise, you need to use HTTPS.
        - JsCallbackwSettings
          - `platform` 'js' — Platform identifier
          - `id` string — The callback URI ID. This must be a universally unique ID (UUID).
          - `url` string — Your project's callback URI, including the protocol. Nylas accepts HTTP for localhost development _only_. Otherwise, you must use HTTPS.
          - `settings` object — Additional platform settings and configurations for the Javascript callback URI.
            - `origin` string, required — The `origin` is the base URL from which your project or app is served. It is required because it's a critical part of defining your app's trust boundaries to prevent cross-origin issues. Set this when you set up OAuth redirect URIs and other security settings.
        - IosCallbackwSettings
          - `platform` 'ios' — Platform identifier
          - `id` string — The callback URI ID. This must be a universally unique ID (UUID).
          - `url` string — Your project's callback URI. This can be HTTPS or a deeplink (for example, `<package/bundle-name>://<deeplink>`). Nylas accepts HTTP for localhost development _only_. Otherwise, you must use HTTPS.
          - `settings` object — Additional platform settings and configurations for the iOS callback URI.
            - `bundle_id` string, required — The `bundle_id` (Bundle Identifier) is a unique identifier for an iOS app. It's set in the Xcode project and follows a reverse domain name style.
            - `app_store_id` string — Unique identifier for your app on the Apple App Store. This ID is assigned to your app when you submit it to the App Store and it is approved.
            - `team_id` string — Unique identifier for your Apple Developer Account or team.
        - AndroidCallbackwSettings
          - `platform` 'android' — Platform identifier
          - `id` string — The callback URI ID. This must be a universally unique ID (UUID).
          - `url` string — Your project's callback URI. This can be HTTPS or a deeplink (for example, `<package/bundle-name>://<deeplink>`). Nylas accepts HTTP for localhost development _only_. Otherwise, you must use HTTPS.
          - `settings` object — Additional platform settings and configurations for the Android callback URI.
            - `package_name` string, required — Find your app's Package Name in the Android Manifest. It's a unique identifier that distinguishes your app on the Google Play Store and on the device. It follows a reverse domain name notation, such as `com.example.myapp`.
            - `sha1_certificate_fingerprint` string, required — A SHA-1 hash of the app's signing certificate. This ensures that only the _signed_ version of your app can use the redirect URI.

## Other responses

- `400` — Bad Request
- `401` — Not Authenticated

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)