Moving to public IDs (UUIDs)

Moving to public IDs (UUIDs)

The ngris API now identifies every object you can address by a uuid instead of an internal integer id. Tunnels, API keys, auth tokens, rate-limit rules, traffic policies, routing rules, RBAC clients and roles, members, invitations, SSO configs, client CAs, dedicated IPs, error templates, traffic logs and more each carry a uuid. Every reference to another object gains a <thing>_uuid field next to the old <thing>_id.

Integer ids are deprecated. They keep working during a 30-day window, then the API refuses them. Endpoints, domains, certificates and applications already used uuids in their URLs; nothing changes there except that the URLs now accept a uuid only.

• Paths take the object's uuid: /v1/tunnels/{uuid}, /v1/keys/auth/{uuid}, /v1/firewall/rate-limits/{uuid}.
• Request bodies and query parameters take <thing>_uuid (endpoint_uuid, role_uuid, ca_uuids) instead of <thing>_id.
• Plans have no uuid: they are addressed by their slug. Send "plan": "team" instead of plan_id; responses carry plan next to every plan_id.
• Responses carry uuid on every object and <thing>_uuid next to every reference. No existing field changes type; the integers are removed at the sunset.

Timeline

Deprecation headers

Until the sunset, every request that sends an integer id where a uuid is expected, in the path, the body or the query string, still succeeds. Its response carries three headers:

• Deprecation (RFC 9745): @ followed by the Unix time the deprecation took effect.
• Sunset (RFC 8594): the HTTP date after which integer ids are refused.
• Link: this page, with rel="deprecation".

Requests that use uuids only never get these headers. Log the headers in your client to find the calls you still have to move. Each such request is also counted on our side, which is how we know when integer use has stopped.

After the sunset

An integer id sent after the sunset, in a path, a body or a query string, is answered with 400 and the code integer_id_unsupported. The param field names the parameter that carried the integer.

Routes that already took a uuid (endpoints, domains, certificates, applications, firewall policies, metric alerts) accept a uuid only. Anything else in that path segment, an integer included, matches no route and gets a plain 404.

The integer id and *_id fields disappear from responses at the same time. Code that still reads them gets nothing.

Paths

These routes took an integer and now take the object's uuid. The integer still works until the sunset, with the deprecation headers.

A child object resolves only under the parent named in the path: a policy rule under its policy, a client session under its client, a rate-limit condition under its rule.

Request bodies and query parameters

Send the new name. The old name still works until the sunset, with the deprecation headers.

• A malformed uuid is 400: {"error": "endpoint_uuid must be a uuid", "param": "endpoint_uuid"}.
• A uuid you can't address, including another account's, is 404, worded exactly like an unknown object.
• Both names sent for different objects is 400 id_uuid_mismatch. For arrays, the two lists must name the same objects in the same order. Send the uuid only.
• Bodies that reject unknown fields accept the new names.

Responses

• Every addressable object carries uuid.
• Every reference <thing>_id gains <thing>_uuid next to it; arrays gain <thing>_uuids in the same order. A *_uuid field is omitted when the reference is empty.
• Every plan_id gains plan (the slug); GET /plans lists each plan's slug.
• Firewall policies and conditions keep their string id (it already was a uuid) and gain uuid with the same value.
• Rows that only appear in lists and that nothing addresses carry no uuid, for example account membership rows, activity and audit-log entries, metric-alert events, incident updates and tunnel agents. Their integer id is removed at the sunset.

Until the sunset responses carry both forms. Switch your code to the uuid fields now; the integer fields are deprecated and disappear at the sunset.

Still integers, by design

These are not our internal ids and don't change: Stripe ids (stripe_*, payment_method_id, invoice and tax ids), the agent's own agent_id, request_id and connection_id, the DNS provider's record_id, GitHub's installation_id and repository ids, and counts, limits, ports and priorities.

Other behaviour changes

• Another account's object is a 404. A uuid or integer of an object outside your active account is answered exactly like an unknown id. A few routes used to answer 403 there and now answer 404: the endpoint API-key routes, dedicated-IP release and group release, and client-CA delete.
• Members: removing or re-roling a user who isn't a member of the account is 404 Member not found (it was 400).
• Case: uuids are accepted in upper or lower case everywhere. Domain, certificate and identity-verification routes used to accept lower case only.
• References are checked: endpoint_uuid / tunnel_uuid on POST /keys/auth, endpoint_uuid on POST /account/objectives and default_role_uuid on the RBAC registration policy must name an object you can address, otherwise the request is 404. The legacy integers are checked the same way.

Webhooks, exports, emails and links

Ids also leave the API in webhooks, files and links. They move to uuids the same way:

• Alert webhooks: the body gains endpoint_uuid next to endpoint_id (rule_uuid was already there). endpoint_id is removed at the sunset; read endpoint_uuid. Slack and Discord messages name the endpoint by its uuid. See Metrics & alerts.
• Traffic-log export: each JSON entry gains uuid and the CSV gains a UUID column (the last one, so no existing column moves). The JSON id and the CSV ID column are removed at the sunset. See Export Traffic Logs.
• Data export (POST /user/data-export): every object carries uuid and every reference <thing>_uuid; the integers are removed at the sunset.
• Account invitation emails link to the invitation by its uuid. A link from an email sent earlier still works until the invitation expires (14 days): the dashboard forwards it to the uuid link.
• Status page: incidents and maintenances live at /status/incidents/<uuid> and /status/maintenances/<uuid>. An older integer link redirects there until the sunset.
• Per-region dedicated-IP groups publish their geo name as grp-<group uuid>.<geo zone> (the geo_fqdn field).
• Support desk: ticket messages name other tickets by uuid, and campaign emails link through the link's uuid; links in emails sent earlier keep working.

MCP server, Python SDK and Kubernetes operator

MCP server

Tools take and return uuids. A numeric id input is accepted as a deprecated alias until the sunset. Assistants re-read tool schemas every session, so nothing to do there; only saved prompts or scripts that quote a numeric id need the uuid instead. See MCP Server.

Python SDK

From ngris 0.2.0 every method takes and returns string uuids: client.tunnels.get(tunnel_uuid), client.api_keys.delete_auth_token(token_uuid), client.billing.checkout(plan="team"), client.endpoints.assign_certificate(endpoint_uuid, certificate_uuid=…). Models expose uuid and the *_uuid fields; their integer fields are optional and deprecated. An integer passed to a method still works until the sunset and emits a DeprecationWarning. Upgrade with pip install -U ngris before the sunset.

Kubernetes operator

From operator 0.2.0 the custom resources record the ngris objects they own by uuid. Resources created by an older operator still hold an integer id in their status; on its next reconcile the new operator looks up the matching uuid and stores it. That lookup needs the integer ids, so upgrade the operator before the sunset.

Dashboard and the agent

Nothing to do in the dashboard. Agent auth token values don't change, so nothing changes on the machines that run the agent.

Migration checklist

1. Find the calls that still send integers: log the Deprecation and Sunset response headers, or search your code for _id fields and numeric path segments.
2. Read the uuid of each object from its list or create response (uuid), and store it instead of the integer.
3. Build paths from the uuid; send *_uuid fields and plan slugs in bodies and query strings.
4. Read uuid / *_uuid from responses; stop reading id / *_id.
5. Upgrade the Python SDK and the Kubernetes operator to 0.2.0 or later.
6. Done when none of your requests gets the deprecation headers any more, before 2026-11-13 23:59:59 UTC.

Every page of the API reference shows the uuid form. Questions: contact us.