# Management API Migration

> For the complete documentation index, see [llms.txt](https://help.1nce.com/llms.txt).

# Management API Migration (v1 → v2)

If you automate against the **1NCE Management API**, you must migrate from **v1** to **v2** before v1 is retired.

<div style={{maxWidth: '420px'}}>

![Deadline December 31, 2026: upgrade to API v2 for all already activated SIM cards](/img/platform-migration/api-v2-deadline.png)

</div>

:::warning Management API v1 retires at the end of 2026
The switch to API v2 must be finalized for all customers by the end of 2026. Plan and test your v2 migration well ahead of the cutoff. See the [Migration Timeline](/platform-migration/timeline/).
:::

## What does not change

- **Base URL:** the API is served from `https://api.1nce.com/management-api` for both versions.
- **Authentication flow:** you still obtain a Bearer token with `POST /oauth/token` (HTTP Basic authentication, `grant_type=client_credentials`), then use the Bearer token on subsequent calls. The authorization spec is version `v2.1.1` for both.
- **Rate limits:** unchanged — default **10 TPS**, with customer-specific overrides on request.

## Authentication and credentials

The way you **obtain and manage credentials** changes in the portal (the token endpoint itself is unchanged):

- Generate credentials under **Account → Management API Access** as OAuth2 **Client-ID + secret** pairs. Create as many as you need.
- **Existing API users keep working** — they were moved here automatically.
- The **Owner role cannot make API calls** — use a dedicated API credential.

See [Portal & API Access](/platform-migration/feature-changes/portal-and-api-access/) for detail.

## Endpoint path change

All SIM Management endpoints move from the `/v1/` prefix to `/v2/`. For example, `GET /v1/sims/{iccid}` becomes `GET /v2/sims/{iccid}`.

### Available in v2

The following SIM Management operations are available in the v2 API:

| Operation | v1 | v2 |
| --- | --- | --- |
| List SIMs | `GET /v1/sims` | `GET /v2/sims` |
| Get / update a SIM | `GET,PUT /v1/sims/{iccid}` | `GET,PUT /v2/sims/{iccid}` |
| SIM status | `GET /v1/sims/{iccid}/status` | `GET /v2/sims/{iccid}/status` |
| Reset connectivity | `POST /v1/sims/{iccid}/reset` | `POST /v2/sims/{iccid}/reset` |
| Events | `GET /v1/sims/{iccid}/events` | `GET /v2/sims/{iccid}/events` |
| Data quota | `GET /v1/sims/{iccid}/quota/data` | `GET /v2/sims/{iccid}/quota/data` |
| SMS quota | `GET /v1/sims/{iccid}/quota/sms` | `GET /v2/sims/{iccid}/quota/sms` |
| Send / list SMS | `GET,POST /v1/sims/{iccid}/sms` | `GET,POST /v2/sims/{iccid}/sms` |
| Get / cancel one SMS | `GET,DELETE /v1/sims/{iccid}/sms/{id}` | `GET,DELETE /v2/sims/{iccid}/sms/{id}` |
| Top up a SIM | `POST /v1/sims/{iccid}/topup` | `POST /v2/sims/{iccid}/topup` |

### Not part of the documented v2 set

Several v1 operations are **not in the current v2 documentation set**. If you depend on any of these, confirm their availability and replacement with 1NCE before migrating:

| Operation | v1 endpoint |
| --- | --- |
| SIM transfer | `POST /v1/sims/simTransfer` |
| Connectivity info | `GET /v1/sims/{iccid}/connectivity_info` |
| Usage | `GET /v1/sims/{iccid}/usage` |
| Bulk top-up | `POST /v1/sims/topup` |
| Auto top-up | `POST /v1/sims/autoTopup` |
| Limits | `GET,POST /v1/sims/limits`, `GET /v1/sims/{service}/limits` |
| Extension | `POST /v1/sims/extension` |

## Hybrid accounts and legacy SIMs

On a [hybrid account](/platform-migration/hybrid-accounts/), the 1NCE Platform 2.0 proxies only a **small subset of Management API endpoints** to the 1NCE Platform 1.0 for legacy SIMs. As a result, some operations available for SIMs native to the 1NCE Platform 2.0 may behave differently — or not be available — for SIMs that are still on the 1NCE Platform 1.0. Test your integration against both legacy and 1NCE Platform 2.0 SIMs during the transition.

## What to do

1. Move your integrations from the `/v1/` endpoints to `/v2/`.
2. Generate (or confirm) credentials under **Account → Management API Access**; stop using the Owner role for API calls.
3. Identify any **v1-only operations** you depend on and confirm their v2 replacement with 1NCE.
4. Test against both **legacy and 1NCE Platform 2.0 SIMs** on a hybrid account.
5. Complete the migration before the **end-of-2026** v1 retirement.

## Try the API

Explore and test endpoints in the interactive API Explorer:

- [API Explorer (v1)](/api/) — current API reference
- [API Explorer (v2)](/api/v2/) — Platform v2 / 1NCE Platform 2.0 API reference