API Versioning

The IdentityMesh Admin API has two path prefixes that return the same responses:

A path-rewrite middleware strips the /v1/ segment before endpoint routing, so both forms resolve to the same handler and produce the same response — bodies, status codes, headers, rate-limiting partition keys, admin-audit rows. There is no separate registration for the v1 prefix; one handler serves both.

When to use which prefix

• External clients, CLI tools, SDK consumers, scripts that will outlive this major version: use /api/v1/. The guarantee is that a future v2 will coexist under /api/v2/ rather than redefining /api/v1/ semantics.
• Components that ship with the product (the Admin Portal, relay agents, the installer): either prefix is fine. The plain /api/ form is currently used and will keep working.

What v1 is committed to

While the v1 designation is in effect, IdentityMesh treats these as breaking changes requiring a v2 (i.e. a second prefix plus a deprecation window on v1):

• Removing an endpoint, or changing its HTTP method.
• Removing a field from a response body, or renaming one.
• Tightening an input contract in a way that rejects previously accepted payloads (e.g. a new required field on a request DTO, or a narrower max length).
• Changing an authorization policy on an endpoint from a .read to a .write scope.

These are fair game within v1 and don’t require a new prefix:

• Adding a new endpoint.
• Adding an optional response field, provided existing clients that ignore unknown keys keep working.
• Adding an optional request field with a sensible default.
• Widening an input contract (e.g. accepting an additional value on an enum-like string).
• Changing internal error shape within the ProblemDetails envelope — callers are expected to key off status and type, not the free-text detail.

Operational notes

• Request logging captures the path after rewrite, so /api/connectors is what ends up in the log stream regardless of which prefix the caller used.
• IM_AdminAudit.Action records the route template, which is the same for both prefixes, so the audit log does not tell v1 callers from legacy callers either. Count them at your reverse proxy or web server access log if you need that figure.
• Swagger UI (Development only) shows the canonical /api/... paths. Both prefixes serve valid requests against those routes.
• Health probes (/health/live, /health/ready) and SignalR hubs (/hubs/*) are outside the /api/ namespace and are not affected by this rewrite.

Future v2

When a breaking change is ready:

1. The new route shape is published under /api/v2/....
2. The v1 routes stay in place — they are not removed in the same release that ships v2. A typical deprecation window is two minor versions; operators get at least one release to migrate.
3. A Deprecation response header (RFC 9745) is stamped on v1 calls during the window so callers discover the cutover without reading changelogs.
4. At the end of the deprecation window, the v1 routes and the v1-to-legacy path mapping are removed in the same release.

Related

• authentication.md — auth schemes are orthogonal to the path prefix; /api/v1/... and /api/... both go through the same SmartAuth / Negotiate / JwtBearer path.