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

# Migrating from v1 to v2

> Step-by-step guide for upgrading from Customer API v1 to v2

<Warning>
  **API v1 is deprecated.** It continues to work but will be removed in a future release. Migrate to v2 to access the full endpoint set, improved authentication, profile management, and invoice operations.
</Warning>

## What Changed

API v2 introduces a versioned URL structure, new endpoint groups, and an optional Bearer token authentication flow alongside the existing API key method.

| Area                    | v1                          | v2                                |
| ----------------------- | --------------------------- | --------------------------------- |
| **Base path**           | `/customer/v1/`             | `/customer/v2/`                   |
| **Auth — API key**      | `X-ORBIT-KEY: <key>` header | Same — unchanged                  |
| **Auth — Bearer token** | Not supported               | `Authorization: Bearer <token>`   |
| **License endpoints**   | `/customer/v1/licenses/...` | `/customer/v2/licenses/...`       |
| **IP whitelisting**     | Flat endpoints              | Nested under `/licenses/{id}/ips` |
| **API key management**  | Not available               | `/customer/v2/api-keys/...`       |
| **Profile**             | Not available               | `/customer/v2/profile/...`        |
| **Invoices**            | Not available               | `/customer/v2/invoices/...`       |

## Authentication — No Change Required

If you authenticate with the `X-ORBIT-KEY` header, **no change is needed for auth**. The same key works with v2.

```bash theme={null}
# Works with both v1 and v2
curl -H "X-ORBIT-KEY: YOUR_API_KEY" https://api.orbitflare.com/customer/v2/licenses
```

Optionally, you can upgrade to Bearer token auth (device flow or wallet signature) for improved security. See the [Auth endpoints](/api-documentation/customer-endpoints/auth/device-code) for details.

## Endpoint Mapping

### Licenses

| v1 Endpoint                                      | v2 Equivalent                                    |
| ------------------------------------------------ | ------------------------------------------------ |
| `GET /customer/v1/licenses`                      | `GET /customer/v2/licenses`                      |
| `GET /customer/v1/licenses/{id}`                 | `GET /customer/v2/licenses/{id}`                 |
| `POST /customer/v1/licenses/{id}/reset-key`      | `POST /customer/v2/licenses/{id}/reset-key`      |
| `POST /customer/v1/licenses/{id}/regenerate-key` | `POST /customer/v2/licenses/{id}/regenerate-key` |
| `GET /customer/v1/locations`                     | `GET /customer/v2/licenses/locations`            |
| `GET /customer/v1/licenses/{id}/ips`             | `GET /customer/v2/licenses/{id}/ips`             |
| `POST /customer/v1/licenses/{id}/ips`            | `POST /customer/v2/licenses/{id}/ips`            |
| `DELETE /customer/v1/licenses/{id}/ips/{ip}`     | `DELETE /customer/v2/licenses/{id}/ips/{ip}`     |

### New in v2 Only

These endpoints do not exist in v1 and are available exclusively in v2:

| Endpoint                                  | Description                           |
| ----------------------------------------- | ------------------------------------- |
| `POST /customer/v2/auth/device/code`      | Initiate device authorization flow    |
| `POST /customer/v2/auth/device/token`     | Exchange device code for access token |
| `POST /customer/v2/auth/wallet/challenge` | Request wallet signature challenge    |
| `POST /customer/v2/auth/wallet/verify`    | Verify wallet signature and get token |
| `GET /customer/v2/api-keys`               | List all API keys                     |
| `POST /customer/v2/api-keys`              | Create a new API key                  |
| `PATCH /customer/v2/api-keys/{id}`        | Update an API key                     |
| `DELETE /customer/v2/api-keys/{id}`       | Delete an API key                     |
| `GET /customer/v2/profile`                | Get user profile                      |
| `PATCH /customer/v2/profile`              | Update user profile                   |
| `GET /customer/v2/profile/balance`        | Get account balance                   |
| `GET /customer/v2/invoices`               | List invoices                         |
| `GET /customer/v2/invoices/{id}`          | Get a specific invoice                |
| `POST /customer/v2/invoices/{id}/pay`     | Pay invoice with account balance      |

## Migration Steps

<Steps>
  <Step title="Update your base URL">
    Change the path prefix in your client from `/customer/v1/` to `/customer/v2/`:

    ```bash theme={null}
    # Before
    curl -H "X-ORBIT-KEY: YOUR_API_KEY" \
      https://api.orbitflare.com/customer/v1/licenses

    # After
    curl -H "X-ORBIT-KEY: YOUR_API_KEY" \
      https://api.orbitflare.com/customer/v2/licenses
    ```
  </Step>

  <Step title="Update the locations endpoint">
    The locations endpoint moved from a top-level path into the licenses group:

    ```bash theme={null}
    # Before
    GET /customer/v1/locations

    # After
    GET /customer/v2/licenses/locations
    ```
  </Step>

  <Step title="Test your integration">
    Run your existing integration against the v2 endpoints. The response shapes for shared endpoints (licenses, IPs) are backward compatible. No response parsing changes should be required for migrated endpoints.
  </Step>

  <Step title="(Optional) Upgrade authentication">
    If you want to use Bearer token auth instead of API keys, implement the [device authorization flow](/api-documentation/customer-endpoints/auth/device-code) or [wallet signature flow](/api-documentation/customer-endpoints/auth/wallet-challenge).
  </Step>
</Steps>

## Need Help?

If you encounter issues during migration, reach out on [Discord](https://discord.gg/orbitflare) or contact [support@orbitflare.com](mailto:support@orbitflare.com).