---
title: "Migrate v2 account to v3 grant"
method: POST
path: "/v3/migration-tools/grants/{account_id}/clone"
tags: ["App migration"]
---

# Migrate v2 account to v3 grant

`POST /v3/migration-tools/grants/{account_id}/clone`

Migrates a single v2 connected account to a v3 grant. Use this endpoint to migrate a few accounts
to v3 as a test, then use the
[Batch Clone endpoint](/docs/reference/api/app-migration/migration_snapshot_batch_clone/)
to migrate the rest.

Before you use this endpoint, your v2 Nylas applications need to be linked to their corresponding v3
applications and you need to have a working equivalent
[authentication connector](/docs/reference/api/connectors-integrations/) for each provider
you use. If you need help with this process, [learn how to get support](/docs/support/).

During migration, Nylas maps the v2 provider to its v3 equivalent using the connected account's
v2 authorization type and provider. All sensitive data (such as tokens and passwords) is encrypted
and securely transfered only within the Nylas infrastructure. No secrets exit the internal Nylas
network.

This endpoint is rate limited to 20 requests per second, per Nylas application ID.

### Create placeholder grants

Nylas can migrate existing Microsoft Graph, Office 365, and EWS accounts that use token
authentication. It can't fully migrate
[some types of Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/#microsoft-account-import-compatibility-in-v3)
because of provider limitations and scope changes in v3.

By default, Nylas creates an invalid v3 Grant with fake credentials for accounts that it can't
automatically migrate. These grants act as "placeholders" that the user can manually authenticate
to later. You can turn this feature off for Microsoft accounts only by setting the `clone_exchange`
query parameter to `false`, or for all providers by setting `allow_invalid_grant_creation` to
`false`.

## Path parameters

- `account_id` string, required

## Query parameters

- `allow_invalid_grant_creation` boolean
- `clone_exchange` boolean

## Response `200`

On success, returns the v3 Grant object Nylas created as part of the migration.

- object
  - `request_id` string — The request ID.
  - `data` GrantObject
    - `account_id` string — The v2 Nylas account ID. This field appears only if the grant was created by migrating a v2 connected account.
    - `blocked` boolean — When `true`, indicates that the grant is blocked from accessing the Nylas APIs.
    - `created_at` integer, required — When the grant was created, in seconds using the Unix timestamp format.
    - `email` string — The email address associated with the grant. If the provider supports `id_token` and exposes the user's email address, Nylas automatically extracts this value.
    - `grant_status` 'invalid' | 'valid' — Specifies whether the grant is valid or the user needs to re-authenticate.
    - `id` string, required — A unique identifier for the grant.
    - `ip` string — The user's client IP address. Mostly useful for [Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).
    - `name` string — The user's display name.
    - `provider` 'ews' | 'google' | 'icloud' | 'imap' | 'microsoft' | 'virtual-calendar' | 'yahoo' | 'zoom' | 'nylas', required — The provider that the user authenticated with.
    - `provider_user_id` string — The user's provider ID. This field might be changed at any time by the provider.
    - `scope` string[], required — An array of [granular scopes](/docs/dev-guide/scopes/) associated with the grant. If none are specified, Nylas uses the default scopes from the [connector](/docs/reference/api/connectors-integrations/).
    - `settings` object — A list of settings associated with the grant. The contents of this object might differ between grants or depending on the provider.
    - `email_aliases` string[] — An array of found email aliases for this grant. Only returned if special query parameter `expose_aliases` for [Get Grant](/docs/reference/api/manage-grants/get_grant_by_id/) is used and set to `true`. Applicable only for Google and Microsoft grants. For Microsoft, aliases require a Microsoft 365 / Exchange Online mailbox. Free Outlook.com (consumer) accounts have no aliases to expose, so this field is omitted from the response even when `expose_aliases=true`.
    - `state` string — The initial state that was set as part of the authentication process. Nylas passes this value back to your project without modifying it. You can use this field for verification, or to track information about the user.
    - `updated_at` integer — When the user last authenticated their grant, in seconds using the Unix timestamp format. Initially, this value is the same as `created_at`.
    - `user_agent` string — The user's [client or browser information](https://www.useragents.me/). Mostly useful for [Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).
    - `workspace_id` string — The ID of the Workspace the grant belongs to, if any. For grants from providers other than Agent Accounts, Nylas may omit this field when the grant is in the application's default workspace.
    - `credential_id` string — The ID of the Credential the grant is associated with. Grant will use this Credential for provider communication.

## 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)