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

# Migrate from v1

> Move a v1 integration to the v2 API with a few small changes.

Your v1 integration keeps working while you move. Use your app's **App ID** and **App Secret** from **Developers → API Settings**.

## What changes in your code

| | v1 | v2 |
| :- | :- | :- |
| **REST base URL** | `https://api.hopae.com/connect/v1` (sandbox: `sandbox.api.hopae.com`) | `https://api.hopae.com/connect/v2` for every app |
| **OIDC authorization** | `/auth` | `/v2/auth` |
| **Which eID** | `providerId: "smartid"` | `connectionId: "smart-id"` |
| **Which data** | `requestedClaims` in each request | The workflow's **Claims** tab in the Console |
| **User input** | `userData`, `matchData` | One `userInput` map, same keys |
| **Minimum assurance** | `requestedLoa` | `acr_values` (OIDC) or a [`check-min-loa` node](/v2/guides/reference/workflow-nodes) |

Sandbox and production apps use the same v2 URLs. The credentials select the app. See [Apps & Environments](/v2/guides/concepts/apps).

<Note>
  The OIDC issuer for v2 is `https://connect.hopae.com` for every app. If your sandbox integration validated `https://sandbox.connect.hopae.com`, update it when you move to `/v2/auth`. See [OIDC Integration](/v2/guides/oidc-integration#endpoints).
</Note>

```json v1 request theme={null}
{ "providerId": "smartid", "requestedClaims": ["name", "birthdate"], "userData": { "registrationId": "PNOEE-38001085718" } }
```

```json v2 request theme={null}
{ "connectionId": "smart-id", "userInput": { "registrationId": "PNOEE-38001085718" } }
```

## What changes in the result

`user` and `match` are unchanged. Check these details:

* `provenance` and `missing_claims` are opt-in: add `provenance=true` and `missing_claims=true` to the userinfo request.
* Provider ids are catalog ids (`smart-id`, not `smartid`), and there is no `amr`. The connection that ran is in `provenance._metadata`.
* `provenance.presentation.credentials[]` holds only the source's `claims` and `evidence`.
* `source_id` is returned only when **Source ID** is ticked on the workflow's **Claims** tab.
* Errors use one envelope: `{ "error": { "code", "message" }, "request_id" }`.

See [Return Data](/v2/guides/verifications/return-data-model).

## Webhooks

Turn on the **Webhook v2** endpoint under **Developers → Webhooks** when your receiver handles the v2 format, then turn **Webhook v1** off. You can run both while you switch. See [Webhooks](/v2/guides/webhook-signing).

## Step by step

<Steps>
  <Step title="Find your connections">
    Look up the connection ID for each v1 provider you use (below), and check that it is activated and enabled in the workflow.
  </Step>

  <Step title="Set the claims">
    Move the claims you sent in `requestedClaims` to the workflow's **Claims** tab. See [Workflows](/v2/guides/verifications/workflows).
  </Step>

  <Step title="Update your code and test with a sandbox app">
    Apply the changes above and run the flow with test credentials. See [Sandbox Testing](/v2/guides/concepts/testing/sandbox-test).
  </Step>

  <Step title="Switch production">
    Deploy the same changes with your production app's credentials.
  </Step>
</Steps>

## Finding your connections

A v1 `providerId` does not map 1:1 to a v2 `connectionId`. A v1 provider corresponds to a v2 **provider**, and a provider offers one connection per credential it can present. Some v1 providers covered several credentials at once (for example `us-id-pass` covered Google Wallet passports from several countries and Aadhaar), so they become several connections in v2.

To find yours:

1. Open **Configuration → Connections** in the Console and filter by provider or country.
2. Pick the row whose credential matches what your v1 integration verified. Its **Connection ID** is the value you use.
3. Activate it, and repeat for every credential you need.

The same information is available from [Get Connections](/v2/api-reference/verifications/get-connections): each item carries `provider.id`, `credential.id`, and `connectionId`.

If you are unsure which connection replaces a v1 provider, ask [support@hopae.com](mailto:support@hopae.com) with the v1 `providerId` and we will map it for you.


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