Skip to main content

Deprecated REST Endpoints and Sunset Dates

OctoMesh moves operations from REST endpoints to CK methods, which you call as typed GraphQL mutations. The REST endpoint of a moved operation keeps working at least until its sunset date; after that it may be removed under the conditions of the window rule. This page lists every deprecated REST endpoint, the method that replaces it and the dates, so you can plan your switch before the sunset.

The window rule​

A REST endpoint is deprecated as soon as the release that deprecates it (its wave) is first delivered to a production environment. Its sunset — the earliest day on which the endpoint may be removed — is to be announced: there is no fixed window, the sunset date is decided once the migration to the methods is implemented, and it is published on this page and announced before it applies.

The "deprecated since" date is therefore set at rollout, not when the release is built; until it is set, the table shows "set at rollout". Until a sunset date is decided, the table shows "to be announced" and no Sunset header is sent. An environment sends the Deprecation and Sunset headers from its first deployment after the matching date is set.

  • Until the sunset the endpoint behaves exactly as before: same route, request and response bodies and status codes. Only the response headers below are added.
  • The endpoint is removed in a release after the sunset date, not on the date itself, and only when the usage count shows that the platform's own clients have switched, and the callers it still shows have been told directly (in addition to the wave announcement). The release notes of that release name it.
  • Moved operations are deprecated in waves. Each wave adds its rows to the table with the release that deprecates them; the release notes announce the wave, and the dates are entered here as soon as they are set or decided.

Deprecated endpoints​

ServiceHTTP method and routeReplacing method (GraphQL field)Deprecated sinceSunsetWave
IdentityPUT {tenantId}/v1/users/{userName}/rolesUser.SetRoles (systemIdentityUsers { setRoles })2026-11-08to be announcedIdentity 1
IdentityPUT {tenantId}/v1/users/{userName}/roles/{roleName}User.AddRole (systemIdentityUsers { addRole })2026-11-08to be announcedIdentity 1
IdentityDELETE {tenantId}/v1/users/{userName}/roles/{roleName}User.RemoveRole (systemIdentityUsers { removeRole })2026-11-08to be announcedIdentity 1
IdentityPOST {tenantId}/v1/users/{userName}/mergeUser.Merge (systemIdentityUsers { merge })2026-11-08to be announcedIdentity 1
IdentityPOST {tenantId}/v1/usersUser.CreateUser (systemIdentityUsers { createUser })set at rolloutto be announcedIdentity (password)
IdentityPOST {tenantId}/v1/users/ResetPasswordUser.ResetPassword (systemIdentityUsers { resetPassword })set at rolloutto be announcedIdentity (password)
BotGET system/v1/jobs?id={jobId}runtime.operations of the backup, restore and archive data methods (systemBotTenantRepositorys { dump, restore, exportArchiveData, importArchiveData }); for a child tenant the same methods with a user token of its parent tenant or of the system tenant (parent-tenant administration)set at rolloutto be announcedBot jobs 1
BotGET system/v1/jobs/download?id={jobId}GET {tenantId}/v1/jobs/download?id={jobId} (the downloadPath of the operation result)set at rolloutto be announcedBot jobs 1
BotDELETE system/v1/jobs/{id}no replacement yet: an operation cannot be cancelled (OD-5); this endpoint still cancels a running job, see the note belowset at rolloutto be announcedBot jobs 1

Switching from the Bot job endpoints. The mapping goes one way: an operation of the backup, restore and archive data methods carries the jobId of its job (in every progress report, in the result and in the job errors), but a jobId cannot be looked up as an operation — runtime.operations reads by operationId or lists by method and state. A job started through the REST endpoints, and every job type without a method (RT import and export, CK import, fixup scripts, secret sweep), has no operation: read it with GET system/v1/jobs?id={jobId}, which keeps working until its sunset. An operation cannot be cancelled; to cancel a running job, call DELETE system/v1/jobs/{id} with its jobId.

Child tenants. An administrator of a parent tenant who backed up or restored a child tenant through {childTenantId}/v1/jobs (or system/v1/jobs) calls the same methods on the child's GraphQL endpoint (/tenants/{childTenantId}/graphQl) with a user token of the parent tenant (or, for a job started through system/v1/jobs, of the system tenant) and reads their operations there; the rule mirrors the REST rule (direct children, the system tenant for every tenant, role TenantManagement in the parent tenant, no client-credentials tokens), see Parent-tenant administration through CK methods. A job that was already started through REST has no operation; read it with GET system/v1/jobs?id={jobId} as above. Only a new call of a method returns an operation.

Routes are relative to the base URL of the service; {tenantId} is the tenant in the route. "Deprecated since" and "Sunset" are UTC days. The GraphQL field is the path below mutation { runtime { … } }, see Typed method mutations.

Announced waves​

No wave is announced at the moment: every operation that already runs through a method and is to be deprecated is in the table above. A future wave is listed here first, without headers and dates, and moves to that table with the release that deprecates it.

Not part of a wave: the account pages of the Identity Service ({tenantId}/api/manage/…, for example change password and set password) run the methods User.ChangePassword and User.SetPassword as well, but they stay as they are and are not deprecated.

The wave "Bot jobs 1" (bot service, configuration key RestDeprecation:Waves:BotJobs1) gets its "deprecated since" date only after every job type that still reports through system/v1/jobs (RT import and export, CK import, fixup scripts, secret sweep) has an operation handle as well; until then the endpoints are marked and counted, but send no Deprecation or Sunset header. Its sunset date follows the window rule like every other wave: it is to be announced.

The wave "Identity (password)" (identity service, configuration key RestDeprecation:Waves:IdentityUsersPassword, Helm value restDeprecation.waves.IdentityUsersPassword) is a wave of its own because it starts with a later release than "Identity 1": the release in which octo-cli and the MCP server create users and reset passwords through the methods. Its "deprecated since" date is the day that release is first delivered to a production environment and is set at rollout; its sunset date follows the window rule: it is to be announced. Until the "deprecated since" date is set, the two endpoints answer exactly as before and add only the Link header. .NET clients of the SDK see IIdentityServicesClient.CreateUser and ResetPassword as obsolete and switch to RtUserMethodClient.CreateUserAsync and ResetPasswordAsync.

What to know when you switch the identity endpoints:

  • User.CreateUser and User.ResetPassword carry a password. Through GraphQL they answer METHOD_HANDLER_NOT_AVAILABLE until the operator enables them (Methods:Identity:EnablePasswordMethods, see Identity Methods).
  • User.CreateUser has no parameter for resetPasswordOnLogin: the REST endpoint sets that flag on the new user after the method stored it, the method alone creates the user without it. If you need the flag, set it after the create with PUT {tenantId}/v1/users/{userName} (see REST Endpoints for Creating Users and Resetting Passwords).
  • The REST password reset sends the user the password-reset e-mail; the method User.ResetPassword sends no e-mail yet. The notification of the method follows with a later release; until then, tell the user yourself when you switch.
  • The role methods look only at the direct roles of a user. The REST endpoints keep their contract for a role held only through a group until they are removed (see REST Endpoints for Roles and Merging).

How a deprecated endpoint tells you​

Every response of a deprecated endpoint carries these headers, whatever the status code (also 400, 401, 403 and 500). Link is sent from the release that deprecates the endpoint on; Deprecation and Sunset follow as soon as their dates are set (see the window rule); while the sunset date is to be announced, there is no Sunset header:

HeaderStandardExampleMeaning
DeprecationRFC 9745Deprecation: @1796083200The endpoint is deprecated since this moment: @ followed by Unix seconds (UTC midnight of the "Deprecated since" day).
SunsetRFC 8594Sunset: Mon, 01 Mar 2027 00:00:00 GMTThe endpoint may be removed from this moment on (HTTP date).
LinkRFC 9745Link: <https://docs.meshmakers.cloud/…>; rel="deprecation"; type="text/html"Documentation of the replacing method.
Link (optional)RFC 5829Link: <https://…>; rel="successor-version"The successor operation, when one is named.

An existing Link header, for example for paging, is kept; the deprecation links are further values of it. The header values are examples, not the dates of a real wave.

What we recommend for an integration:

  1. Log the headers. Have your HTTP client log a warning when a response carries Deprecation, Sunset or a Link with rel="deprecation", with the route and the sunset date. Then you learn about a deprecation from your own logs, not only from release notes.
  2. Check the OpenAPI description. The service's OpenAPI document (Swagger UI) marks a deprecated operation as deprecated (shown struck through) and adds "Sunset <date>, use <link>." to its description ("Deprecated, use <link>." while the sunset date is not set yet). Generated clients usually turn this into a compiler warning.
  3. Switch before the sunset. Call the replacing method as a GraphQL mutation; the linked method page describes its parameters, result and error codes.

Who still calls a deprecated endpoint​

The platform counts the calls of every deprecated endpoint per endpoint, OAuth client id and status class (metric octo.rest.deprecated.calls). This tells the operator which clients still need to switch before an endpoint is removed. The count holds the route template (for example POST /{tenantId}/v1/users), never a tenant id, user name or parameter. The service accounts of pipelines (octo-pipeline-sa-{adapterRtId}) are counted as one client, octo-pipeline-sa.

If you run your own integration with its own client id, your calls show up under that client id. Removing an endpoint after the sunset is decided on this count: first-party clients must have switched, and the callers the count still shows must have been told directly; that notice is recorded separately, the count does not show it.

See also​