> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate with an AI agent

> Install the OFAuth migration skill so your coding agent moves your V2 integration to V3

The `ofauth-v2-to-v3-migration` skill teaches a coding agent, such as Claude Code, Codex, or Cursor, how to move your codebase from V2 to V3. It follows the [migration guide](/guides/migrate-v2-to-v3) and the V3 reference.

The skill changes your code only. You still run the organization migration in the OFAuth dashboard.

## What the agent does

1. **Finds V2 usage.** It searches for API keys (`sk_live_...`, `sk_test_...`, `sk_sandbox_...`), `api.ofauth.com/v2` calls and the raw access proxy, `x-connection-id`, Link embed and `/v2/link/init`, `/v2/account*`, `/v2/vault-plus`, V2 SDKs, and webhook receivers that read `svix-*` headers.
2. **Plans the changes.** It maps each use to a V3 operation and scope, and lists V2 routes that have no V3 operation yet and features V3 removes. It shows you the plan before large edits.
3. **Rewrites the integration.** OAuth with PKCE at `https://auth.ofauth.com/link/authorize`, the token endpoint with `client_secret_basic`, refresh tokens stored for each `linked_account_id`, `/v3/access/*` with `x-linked-account-id`, `/v3/vault-plus/*`, `/v3/linked-accounts`, Standard Webhooks headers, lifecycle events, and V3 error recovery.
4. **Builds the account bundle import.** A script that imports the one-time account bundle after cutover. It stores each new refresh token and can safely run again.
5. **Verifies.** It runs your tests, checks that no V2 calls remain, and walks you through the Test rehearsal, the Live token request, and the cutover-day steps.

## Install the skill

The skill is a folder of plain Markdown files: `SKILL.md` and a `references/` folder. It is published at `https://ofauth.com/skills/ofauth-v2-to-v3-migration/`, and `files.txt` in that folder lists every file. Run the install command from your repository root.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    base=https://ofauth.com/skills/ofauth-v2-to-v3-migration dir=.claude/skills/ofauth-v2-to-v3-migration; curl -fsSL "$base/files.txt" | while read -r f; do curl -fsSL --create-dirs -o "$dir/$f" "$base/$f" || exit 1; done
    ```

    Claude Code loads skills from `.claude/skills/`. To use the skill in every project, set `dir=~/.claude/skills/ofauth-v2-to-v3-migration` instead.
  </Tab>

  <Tab title="Codex and others">
    ```bash theme={null}
    base=https://ofauth.com/skills/ofauth-v2-to-v3-migration dir=.agents/skills/ofauth-v2-to-v3-migration; curl -fsSL "$base/files.txt" | while read -r f; do curl -fsSL --create-dirs -o "$dir/$f" "$base/$f" || exit 1; done
    ```

    Codex and other agents that support Agent Skills load skills from `.agents/skills/`. If your agent does not load skills, add this line to your `AGENTS.md`:

    ```markdown theme={null}
    When migrating OFAuth from V2 to V3, follow .agents/skills/ofauth-v2-to-v3-migration/SKILL.md and read the reference files it links.
    ```
  </Tab>

  <Tab title="Cursor">
    Download the files with the **Codex and others** command, then add a rule at `.cursor/rules/ofauth-v2-to-v3-migration.mdc`:

    ```markdown theme={null}
    ---
    description: Migrating the OFAuth integration from V2 to V3
    globs:
    alwaysApply: false
    ---
    When migrating OFAuth from V2 to V3, follow .agents/skills/ofauth-v2-to-v3-migration/SKILL.md and read the reference files it links.
    ```
  </Tab>
</Tabs>

On Windows, run the command in Git Bash or WSL.

## Start the migration

Open your agent in the repository and paste:

```text theme={null}
Migrate this codebase from OFAuth V2 to V3 using the ofauth-v2-to-v3-migration skill. Start by finding every V2 usage and show me the plan before you edit code. Build the account bundle import too. Do not add real secrets to any file.
```

Plan for the steps only you can do:

* Run the organization migration in the dashboard, review the Live callbacks, and save the Live client secret.
* Fill in the client IDs, client secrets, and webhook secret in your configuration.
* Run the Test rehearsal and the Live token request.
* After cutover, download the account bundle and run the import.

## Safety

<Warning>
  The account bundle holds one refresh token for each migrated account. Treat it like your client secret: never commit it, paste it into an agent chat, or share it. Run the import yourself, then delete the file. If you lose it, an owner can regenerate it, which revokes every token from the previous bundle.
</Warning>

* Review every diff before you merge. Pay most attention to token storage, the OAuth callback, and webhook verification.
* Keep secrets in your secret manager or environment, not in code, fixtures, or prompts.
* Run the full test suite and rehearse in Test before you schedule cutover.
* If your app uses a V2 route with no V3 operation, or a raw proxy path, contact [support@ofauth.com](mailto:support@ofauth.com) with the path before you schedule cutover.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.