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

# Migrating from v1 to v2

> What changes when you move an existing integration from v1 to v2

# Migrating from v1 to v2

<Note>
  This page is for carriers and MGAs with an existing `/v1/*` integration. There was never a v1 agency surface, so an agency has nothing to migrate: start at [Getting Started for Agencies](/guides/downstream-getting-started). `/v2/upstream` carries 48 of v1's 55 operations. The seven it does not are the four auth and heartbeat paths, which moved to the unsegmented `/v2/auth/*` and `/v2/heartbeat`, and the three deprecated `dangerously-` endpoints listed below, each of which names its successor. `v2` adds no upstream operation that `v1` lacks.
</Note>

**This is a path change.** Request bodies, query parameters, response shapes and status codes are identical between `v1` and `v2`. There is no field renaming, no envelope change and no new required parameters.

<Note>
  One endpoint differs, additively. `GET /v2/auth/test-oauth` returns an extra `orgCategory` field naming the kind of organization your credential belongs to; the v1 response does not. Nothing is removed or renamed, so a client that ignores unknown fields needs no change.
</Note>

You do not have to migrate. `v1` is stable, fully supported and has no sunset date. Migrate when you want the endpoints that will only be added to `v2`.

## 1. Change the path prefix

Replace `/v1/` with `/v2/upstream/`:

```bash theme={null}
# Before
curl "https://public.api.live.turrisfi.com/v1/agents" \
  -H "Authorization: Bearer YOUR_TOKEN"

# After
curl "https://public.api.live.turrisfi.com/v2/upstream/agents" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

For most integrations this is a one-line change to a base URL constant.

`upstream` identifies the kind of organization your credentials belong to. See [versioning](/guides/versioning) for the full persona model and why it was introduced.

## 2. Authentication is unchanged

Your existing client ID and secret work as-is. No new credentials, no re-issuing tokens.

The token endpoint moves to `/v2/auth/jwt` and takes **no persona segment**, because the token itself identifies your organization:

```bash theme={null}
curl -X POST "https://public.api.live.turrisfi.com/v2/auth/jwt" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET"}'
```

`GET /v2/heartbeat` is likewise persona-neutral.

Tokens are interchangeable between versions. A token minted at `/v1/auth/jwt` is accepted by `/v2/upstream/*`, so you can migrate endpoint by endpoint rather than all at once.

## 3. Three endpoints are not in v2

These were deprecated in `v1` and are absent from `v2`. Each has a direct replacement with an identical request and response:

| Not in v2                                                                   | Use instead                                                              |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `POST /v1/downstream-entity-associations/dangerously-invite`                | `POST /v2/upstream/downstream-entity-associations/invite`                |
| `POST /v1/downstream-entity-associations/dangerously-add`                   | `POST /v2/upstream/downstream-entity-associations/add`                   |
| `GET /v1/downstream-entity-associations/licenses/dangerously-surplus-lines` | `GET /v2/upstream/downstream-entity-associations/licenses/surplus-lines` |

If you call any of these on `v1` today you will receive `Deprecation`, `Sunset` and `Link` response headers. They remain available on `v1` until the sunset date of **1 January 2027**.

<Warning>
  Switching from a `dangerously-` endpoint to its replacement is a rename only. The request body and the response are the same, so it is safe to make this change on `v1` before you migrate to `v2`, and we recommend doing so.
</Warning>

## 4. Everything else maps one to one

Every other `v1` endpoint exists on `v2` at the same path with the new prefix. Some examples:

| v1                                       | v2                                                |
| ---------------------------------------- | ------------------------------------------------- |
| `GET /v1/agents/{agentId}/licenses`      | `GET /v2/upstream/agents/{agentId}/licenses`      |
| `GET /v1/downstream-entity-associations` | `GET /v2/upstream/downstream-entity-associations` |
| `POST /v1/policies`                      | `POST /v2/upstream/policies`                      |
| `GET /v1/webhooks`                       | `GET /v2/upstream/webhooks`                       |

Browse the full list with the version switcher at the top of the [API Reference](/api-reference/v2/heartbeat/health-check).

## Suggested approach

1. Point one non-critical read endpoint at `/v2/upstream/` in sandbox and confirm the response matches what you already parse.
2. Move the remaining reads. Responses are identical, so no parsing changes are needed.
3. Move writes, replacing any `dangerously-` calls with their successors.
4. Update your token endpoint to `/v2/auth/jwt`.

Because tokens work across versions and the shapes match, a partial migration is a valid resting state. There is no deadline.

## Getting help

Something not behaving identically between `v1` and `v2` is a bug on our side, not an expected difference. Email [support@turrisfi.com](mailto:support@turrisfi.com) with the endpoint and both responses.


## Related topics

- [Getting Started for Carriers & MGAs](/guides/getting-started.md)
- [The Carrier & MGA API](/guides/carrier-api.md)
- [Tools & Integrations](/guides/tools-and-integrations.md)