Sign in
App migration

Link a v2 app to a v3 app

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.

--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.

post/v3/migration-tools/link-v2v3-apps

Response

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

request_idstring

The request ID.

Example response

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "application_id": "ad410018-d306-43f9-8361-fa5d7b2172e0",
    "organization_id": "f5db4482-dbbe-4b32-b347-61c260d803ce",
    "region": "us",
    "default_workspace_id": "abf6ff99-05ad-4c0a-aaf8-400aacf2470a",
    "v2_application_id": "9nsr7pjw1e1g6hgy9l1znjql7",
    "branding": {
      "name": "My application",
      "icon_url": "https://my-app.com/my-icon.png",
      "website_url": "https://my-app.com",
      "description": "Online banking application."
    },
    "hosted_authentication": {
      "background_image_url": "https://my-app.com/bg.jpg",
      "color_primary": "#dc0000",
      "color_secondary": "#000056",
      "background_color": "#003400",
      "spacing": 5
    },
    "callback_uris": [
      {
        "id": "0556d035-6cb6-4262-a035-6b77e11cf8fc",
        "url": "https://yourapp.com/callback"
      }
    ]
  }
}

Changes