Legacy Authority Authentication Endpoints — Deprecation Guidance

Announced: 1 November 2025
Sunset (removal no earlier than): 1 May 2026

This guide tells operators and integrators how to migrate off the deprecated /oauth/* authentication aliases in StellaOps Authority before they are retired, and documents the deprecation headers, configuration, and audit signals emitted in the meantime.

Summary

StellaOps Authority previously exposed OAuth 2.1 endpoints at /oauth/token, /oauth/revoke, and /oauth/introspect to ease migration from early previews. Those aliases are now deprecated in favour of the canonical paths (/token, /revoke, /introspect). All responses from the legacy routes include:

Deprecation — RFC 1123 / RFC 7231 HTTP-date. Defaults to Sat, 01 Nov 2025 00:00:00 GMT (configurable via apiLifecycle.legacyAuth.deprecationDate).
Sunset — HTTP-date advertising the planned removal. Defaults to Fri, 01 May 2026 00:00:00 GMT (configurable via apiLifecycle.legacyAuth.sunsetDate).
Warning — RFC 7234 299 warning of the form 299 - "Legacy Authority endpoint will be removed after <sunset HTTP-date>. Migrate to canonical endpoints before the sunset date.".
Link — rel="sunset" URI pointing to migration guidance. Emitted only when apiLifecycle.legacyAuth.documentationUrl is configured (default https://docs.stella-ops.org/authority/legacy-auth).

No new features (DPoP nonces, audit upgrades, policy scopes) will ship on the legacy routes.

Implementation note (verified against src/Authority). The legacy routes are served by LegacyAuthDeprecationMiddleware, which transparently rewrites /oauth/token, /oauth/introspect, and /oauth/revoke to the canonical /token, /introspect, and /revoke paths and forwards the request to the same OpenIddict handlers (canonical endpoints are registered in Program.cs via SetTokenEndpointUris("/token") / SetIntrospectionEndpointUris("/introspect") / SetRevocationEndpointUris("/revoke")). The middleware does not currently contain any date-based logic, so the aliases do not automatically begin returning 410 Gone on the sunset date. The shim is controlled entirely by the apiLifecycle.legacyAuth.enabled configuration flag (default true); operators turn the shim off — or a future release removes the middleware — to retire the aliases. When the shim is disabled the rewrite no longer applies and requests to /oauth/* fall through to standard routing (today there is no canonical handler bound at /oauth/*, so they return 404). The 410 Gone behaviour described below is the planned retirement contract, not the current runtime behaviour.

Required Actions

Service identities / CI pipelines – Update token, revocation, and introspection calls to target the canonical /token, /revoke, and /introspect endpoints. Regenerate OpenAPI clients if they relied on the deprecated paths.
Gateway / proxy rules – Remove explicit rewrites that target /oauth/* so traffic flows directly to the canonical paths.
Custom SDKs – Regenerate against the refreshed Authority OpenAPI spec (/.well-known/openapi) which marks legacy operations as deprecated: true.
Monitoring – Alert on the authority.api.legacy_endpoint audit event or the 299 Warning header to verify migrations are complete.

Configuration

The shim is configured under apiLifecycle.legacyAuth in the Authority configuration (e.g. authority.yaml; see etc/authority.yaml.sample). The settings are bound to AuthorityLegacyAuthEndpointOptions and validated on startup.

Key	Type	Default	Notes
`apiLifecycle.legacyAuth.enabled`	bool	`true`	Master switch for the shim. When `false`, no rewrite or deprecation headers are emitted and `/oauth/*` requests fall through to normal routing.
`apiLifecycle.legacyAuth.deprecationDate`	date-time	`2025-11-01T00:00:00Z`	Emitted in the `Deprecation` header (RFC 1123 format) and the `legacy.deprecation_at` audit property.
`apiLifecycle.legacyAuth.sunsetDate`	date-time	`2026-05-01T00:00:00Z`	Emitted in the `Sunset` header and `Warning`/`legacy.sunset_at`. Validation requires `sunsetDate` to be strictly after `deprecationDate`.
`apiLifecycle.legacyAuth.documentationUrl`	string (http/https URL)	`https://docs.stella-ops.org/authority/legacy-auth`	When set, emitted as the `Link; rel="sunset"` header. Validated to be an absolute `http`/`https` URI; set to empty to suppress the `Link` header.

The notificationTopic key shown in some configuration samples is not bound by AuthorityLegacyAuthEndpointOptions and has no runtime effect; it is illustrative only.

Audit event details

When the shim handles a legacy request it writes one authority.api.legacy_endpoint audit event (AuthEventRecord) via the audit sink, with Outcome = Success. The event carries these properties for dashboards and alerting:

Property	Value
`legacy.endpoint.original`	The legacy path that was called (e.g. `/oauth/token`).
`legacy.endpoint.canonical`	The canonical path the request was rewritten to (e.g. `/token`).
`legacy.deprecation_at`	Configured deprecation date (ISO-8601).
`legacy.sunset_at`	Configured sunset date (ISO-8601).
`http.status_code`	The downstream HTTP status code returned to the caller.

The event also records correlation id (current trace id) and best-effort network details (remote address, X-Forwarded-For, user agent), all classified as personal data.

Timeline & Support

Date	Milestone
1 Nov 2025	Deprecation headers emitted, documentation published
Jan–Apr 2026	Observability dashboards highlight remaining usage; support assists with migrations
1 May 2026	Earliest planned retirement. Note: retirement is not automatic on this date — an operator setting `apiLifecycle.legacyAuth.enabled: false`, or a release that removes `LegacyAuthDeprecationMiddleware`, is what retires the aliases. The intended end-state contract is `410 Gone` (or `404` if the routes are simply unregistered), after which they will be removed in the next major release.

Questions? Contact the Authority Core guild or open a ticket with the API Governance Guild referencing AUTH-OAS-63-001.