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
| Service | HTTP method and route | Replacing method (GraphQL field) | Deprecated since | Sunset | Wave |
|---|---|---|---|---|---|
| Identity | PUT {tenantId}/v1/users/{userName}/roles | User.SetRoles (systemIdentityUsers { setRoles }) | 2026-11-08 | to be announced | Identity 1 |
| Identity | PUT {tenantId}/v1/users/{userName}/roles/{roleName} | User.AddRole (systemIdentityUsers { addRole }) | 2026-11-08 | to be announced | Identity 1 |
| Identity | DELETE {tenantId}/v1/users/{userName}/roles/{roleName} | User.RemoveRole (systemIdentityUsers { removeRole }) | 2026-11-08 | to be announced | Identity 1 |
| Identity | POST {tenantId}/v1/users/{userName}/merge | User.Merge (systemIdentityUsers { merge }) | 2026-11-08 | to be announced | Identity 1 |
| Identity | POST {tenantId}/v1/users | User.CreateUser (systemIdentityUsers { createUser }) | set at rollout | to be announced | Identity (password) |
| Identity | POST {tenantId}/v1/users/ResetPassword | User.ResetPassword (systemIdentityUsers { resetPassword }) | set at rollout | to be announced | Identity (password) |
| Bot | GET 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 rollout | to be announced | Bot jobs 1 |
| Bot | GET system/v1/jobs/download?id={jobId} | GET {tenantId}/v1/jobs/download?id={jobId} (the downloadPath of the operation result) | set at rollout | to be announced | Bot jobs 1 |
| Bot | DELETE system/v1/jobs/{id} | no replacement yet: an operation cannot be cancelled (OD-5); this endpoint still cancels a running job, see the note below | set at rollout | to be announced | Bot 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.CreateUserandUser.ResetPasswordcarry a password. Through GraphQL they answerMETHOD_HANDLER_NOT_AVAILABLEuntil the operator enables them (Methods:Identity:EnablePasswordMethods, see Identity Methods).User.CreateUserhas no parameter forresetPasswordOnLogin: 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 withPUT {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.ResetPasswordsends 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:
| Header | Standard | Example | Meaning |
|---|---|---|---|
Deprecation | RFC 9745 | Deprecation: @1796083200 | The endpoint is deprecated since this moment: @ followed by Unix seconds (UTC midnight of the "Deprecated since" day). |
Sunset | RFC 8594 | Sunset: Mon, 01 Mar 2027 00:00:00 GMT | The endpoint may be removed from this moment on (HTTP date). |
Link | RFC 9745 | Link: <https://docs.meshmakers.cloud/…>; rel="deprecation"; type="text/html" | Documentation of the replacing method. |
Link (optional) | RFC 5829 | Link: <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:
- Log the headers. Have your HTTP client log a warning when a response carries
Deprecation,Sunsetor aLinkwithrel="deprecation", with the route and the sunset date. Then you learn about a deprecation from your own logs, not only from release notes. - 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. - 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
- Identity Methods — the methods of the first wave
- Method Definitions — what a CK method is
- GraphQL mapping of methods — how to call one
- API Integration — authentication and the REST API in general