Recommendation: You should migrate to header-based authentication now to protect connections and prevent credentials in logs. The November 2025 deprecation targets all parameter and body-based authentication usage. Move to Authorization: Bearer tokens and enforce samesite cookies for token refresh where applicable. This change exposes fewer sensitive data surfaces.

Migration mode options include automatic token rotation and per-section rollouts that support distribution across environments. For models relying on multiple backends, centralize checks in a dedicated servlet filter and surface status on the dashboard. The major update keeps credentials out of parameter and body flows and clarifies what changed for developers, security teams, and operators, including the amount of endpoints affected.

Migration steps: identify all endpoints containing credentials in parameters or body and mark them as switched in the section describing authentication. Replace credential checks with Authorization: Bearer tokens in the HTTP header. Enforce samesite cookies for refresh tokens and implement automatic rotation where needed. Validate the distribution of changes across environments to ensure consistent connections handling for models and external services. Remove support for legacy query and body authentication in a final section of the docs.

Teams ready to proceed can use the dashboard's migration section and the accompanying notes in the DeepL Documentation to track progress. The November 2025 release notes provide concrete guidance for developers, security staff, and operators to adopt header-based authentication across services and keep protected resources sealed behind proper access controls.

Key dates and migration window for query parameter and request body authentication

Start the migration in a two-phase window from 1 November 2025 to 29 November 2025, with staged rollouts and abort criteria clearly defined.

  1. 2025-11-01 – Planning and inventory: catalog deployments, multi-site distribution, and memory usage; map infinispan caches; appoint owners (ingrid, shigeyuki) and align on the usernameless approach where applicable; verify private_key_jwt readiness and ensure keycloak_session compatibility.
  2. 2025-11-08 – Dry-run in staging: execute a representative set of func calls to validate query parameter and request body authentication paths; collect response times, token validity, and feedback from operators; ensure past configurations are represented in the test data.
  3. 2025-11-15 – Production cutover for low-risk deployments: enable the new authentication path via feature flags (setting and menu toggles); monitor for invalidated sessions and abort if critical errors appear; confirm that major flows execute successfully and that prompts are surfaced through promptcreate interfaces.
  4. 2025-11-22 – Broad rollout and validation: extend to broader distribution, including multi-site environments; track memory and scheduling metrics; verify that execution across deployments completes within SLA and that response payloads match expectations.
  5. 2025-11-29 – Final verification and deprecation milestone: deactivate legacy query parameter and request body checks in all non-critical paths; document the changes for ingrid’s team and update internal catalogs; gather feedback for future improvements and confirm that deployments continue to run without invalidated tokens.

Key considerations by area ensure a smooth transition. deployments across multi-site setups receive aligned updates, while memory and infinispan caches remain within target bounds. setting changes apply gradually and are represented consistently across environments. the private_key_jwt flow is tested against real-world response scenarios, with abort points defined for token misbehavior. the broader schedule allows shigeyuki and ingrid to coordinate releases and collect feedback, which prompts promptcreate updates and menu-driven configuration changes where needed.

Step-by-step migration to header-based authentication with concrete examples

Replace query parameter authentication with header-based authentication across all endpoints. Use a single header such as auth_api_key or Authorization: Bearer, and stop relying on query strings. During a controlled window, continue to emit logs for old query-parameter usage while enforcing header checks. This approach yields higher security, reduces exposure of credentials, and aligns with lightweight server-side validation. For contents about their services, keep the login flow consistent and prepare a common template for error responses. Welcome to the migration, shigeyuki and their team; this plan covers concrete actions and commands to complete the change.

  1. Assessment and inventory of contents and endpoints
    • List endpoints that accept or rely on query-based credentials, including /contents, /pages, /login, /members, and child resources. Capture the existing reads and writes and map them to a header-based path.
    • Extract existing mappers that translate external credentials into internal struct fields. If a mapping exists, reuse it and extend it to read headers like auth_api_key or Authorization.
    • Record expected responses (status, payload shapes) for each endpoint and note any bytes overhead added by the header-based approach.
    • Create a centralized contents table listing endpoints, their methods, and whether they exist in documentation pages. This list becomes the backbone of the migration plan.
  2. Define the header-based scheme and server-side validation
    • Choose a primary header: auth_api_key. Optionally support Authorization: Bearer during the transition, but require a single source of truth for production.
    • Update the request struct to include a header field for credentials. Ensure the handler reads either req.headers.auth_api_key or req.headers.authorization and normalizes to internal credentials objects.
    • Implement a lightweight lookup against a credentials store or a mappers list. Validate the token against the expected identity, and return 200 on success or 401/403 on failure.
    • Provide a response template for missing or invalid headers to keep error payloads consistent across pages and services.
    • Tests should confirm that reads on contents, pages, and login endpoints succeed only when the header is present and valid.
  3. Server changes and example commands
    • Middleware draft:

      If req.headers.auth_api_key exists, map to internal credentials and proceed. Else if req.headers.authorization exists and begins with Bearer, extract the token and map as a fallback. Otherwise respond with 401 Unauthorized.

    • Example tests you can run (adjust host names as needed):

      Test the header path for a contents read: curl -H "auth_api_key: YOUR_API_KEY" https://api.example.com/v1/contents/123

      Test an error when the header is missing: curl -i https://api.example.com/v1/contents/123

      Test using Bearer during transition: curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/v1/pages

      Test login via header and credential lookup: curl -H "auth_api_key: YOUR_API_KEY" -X POST https://api.example.com/v1/login

    • Notes: ensure existing copies of credentials are not embedded in URLs and that bytes of header values stay within typical limits (a few dozen to a few hundred bytes).
  4. Client library updates and migrating their code
    • Update each client to send a header on every request. For example, migrate from query=params to headers in contents, pages, and login requests.
    • Provide a single source of truth for credentials; keep a local template that clients populate with their their login flow results and then pass as auth_api_key or Authorization header.
    • Optionally support both headers during the migration window, but prefer a unified header in production to reduce surface area.
    • Example client adjustments:

      Node.js: fetch(url, { headers: { auth_api_key: "" } })

      Python: requests.get(url, headers: {"Authorization": "Bearer "})

      Go: http.NewRequest("GET", url, nil); req.Header.Set("auth_api_key", "")

    • Update the mappers to translate the header value into the internal credentials struct used by the authentication layer. This ensures parity with existing reads and support for child resources and nested pages.
  5. Migration plan, rollout, and verification
    • Define a window where both methods are accepted, log usage, and then gradually disable query-param authentication. Track success by the number of successfully authenticated requests and the decrease in query-param hits.
    • Expect a temporary rise in 401/403 responses during client updates; adjust clients, and then remove the old code path later.
    • Prepare a browser-friendly login path that sets a session-like header for subsequent requests. Ensure the template responses for invalid credentials remain stable and predictable.
    • Communicate progress to team members with clear milestones. Copies of the plan should exist in a shared location, and a weekly summary keeps everyone aligned.

Pre-migration checks

Post-migration verification

Testing and validation: how to verify successful authentication post-migration

Begin validation by testing authentication at each endpoint immediately after migration, targeting the new flow within the enterprise context. Use automated checks and targeted manual tests to confirm login, token refresh, and secure cookie handling across services, ensuring consistent results across environments within the stack.

Capture a defined set of test credentials using a standardized baseline, and verify that the token signature matches the expected algorithm and that the hash of the credential data is reproducible for a given input, using a mix of automation and manual checks.

Validate ldaps connections and directory lookups, ensuring authentication results are consistent across distributed components, including tomcat-based frontends and backend services.

Track observedgeneration in orchestration if applicable, and relying on a centralized identity provider, perform a review of alignment between identity data and service endpoints, ensuring defined session limits and refresh windows are respected.

Populate test credentials using import and copyimport options to reproduce real usage; maintain a contextual menu with a custom login option and verify that credential handling remains consistent across environments.

For a particular endpoint, validate that the authentication context remains contextual and that general information about the user maps correctly to enterprise roles via the component's authorization policy.

Impose limits on retry, lockout, and session duration; monitor performance under distributed load across tomcat clusters and other services to detect anomalies in authentication timing.

Enable centralized logging and a thorough review process; collect information on each attempt, time-to-auth, and signature verification time to identify deviations from baseline.

Record every contribution from security and development teams to expand test coverage and confidence; store a reference hash and credential trail in a defined repository, accessible to enterprise stakeholders.

Offer a concise post-migration validation checklist and a consolidated report covering endpoint coverage, ldaps health, signature and hash checks, observedgeneration, and credential handling workflows.

New Account Console default: impact on access flows, sessions, and user setup

Adopt the new Account Console default now and apply a 24-hour rollback window during rollout to prevent disruption for teams using legacy paths.

The default renamed security model enforces stricter binding between requests and sessions, and forwarded headers are validated at the backend to block spoofing. It tightens the TLS context via https-trust-store- usage, ensuring all read operations run over trusted channels.

The default increases flexibility by supporting rolling updates and optionally mapping folders and subfolders to user attributes. The backend sets session lifetimes and stores them centrally, while calling clients receive consistent tokens via a single method, simplifying maintenance.

User setup now highlights lastname as a standard field, and jakarta deployments must ensure proper federation metadata. The system reads and writes profile data in the backend, while artifact fields in federation metadata are respected during saml binding. Members and admins can review a title alias and grouping within folders; artifact attributes may influence role mapping. If a user is redirected from an external IdP, the protocol enforces a clean attribute map and avoids unencrypted endpoints.

The federation layer uses the saml protocol to exchange artifacts, with redirected endpoints and the option to use jakarta-compatible metadata. Elytron remains the security gatekeeper, enforcing the selected method and ensuring tokens are read and verified before access is granted.

Operational notes: monitor dashboards for forwarded changes and ensure access continues for members while validating folder and subfolder permissions. Verify that unencrypted endpoints remain disabled and prepare updated admin guides that reflect the new default title labeling and the renamed fields.

SDK and library guidance: version requirements, deprecation flags, and practical code samples

Concrete action: Pin SDK to 6.x minimum across stacks and enable deprecation flags in config to surface legacy usages early. Move temporary authentication paths from query parameters toward header-based schemes or webauthn, and enable automatic binding in the client so new requests bind tokens without manual changes.

Version requirements align with platform support: Node.js 18+, Python 3.11+, Java 17+. For openshift deployments, ensure the cluster supports TLS 1.3 and includes up-to-date certificates. Schedule date1 for rotation in your organization’s setup and propagate updates across stacks via shared specifications and types.

Flag behavior: Enable DEPRECATION_STRATEGY to report warnings or fail on deprecated calls. When a deprecated parameter is read, the API fires a deprecation event and returns the same response shape until clients migrate. Apply this policy across services to keep tracking consistent and minimize breaking changes.

Practical code samples: Implement quick checks and migration hooks in your code path. Example (JS/TS):

export const sdkConfig = { deprecationWarnings: true, deprecationStrategy: 'warn' };

const client = createClient({ setup: sdkConfig, apiBase: '/api' });

const res = await client.get('/models?queries=active');

The same approach applies to binding layers: when you upgrade to a newer models/types, the client automatically resolves apiassetsmyfoldermyassetpng and related artifacts, showing the evolution of services and their responses in a single dashboard. This helps teams in the organization correlate codes, date1 references, and certificates during setup.

The dashboard offers a descriptive view of deprecation signals across stacks, services, and models. It shows affected queries and responses, lists artifacts such as apiassetsmyfoldermyassetpng, and links to certificates and codes. This visibility supports self-service checks and makes it easier to coordinate across date1 renewal cycles and social teams that monitor changes on openshift and other platforms.

Security improvements: best practices for token handling and minimizing exposure

Issue short-lived access tokens (15-60 minutes) and require a refresh flow; pair with rotating signing keys to limit impact when a token leaks, and apply upgrades via config-driven key timelines.

Centralize validation in an enforcer that does not trust client input; verify atjwt signatures, issuer, audience, ft-date expiry, and scopes on every request, and map extracted claims to values used by authorization decisions.

Store tokens in trusted channels: httpOnly Secure cookies or encrypted in-memory stacks; avoid embedding tokens in URLs or logs. Include only non-sensitive cover messages, and use a stringbuilder to format logs and user messages without exposing token content.

Specify interfaces and methods for token handling; the creating and validating logic holds within modular components, reducing surface area and easing upgrades involved across services. This structure prevents hidden data leaks and clarifies responsibility boundaries.

Logging and monitoring emphasize safety: log non-sensitive details, include message identifiers, and track hour-based error rates. Ensure website pages and dashboards don’t reveal secrets, and import policy updates to downstream services without leaking credentials.

Overview and governance focus on limits and provenance: extend controls over allowed values, group-related claims, and ciam-backed workflows; define meaning for each claim and ensure config-driven behavior stays consistent during upgrades and across stacks.

AspectRecommendationRationale
Token lifetimeUse short lifetimes (15-60 minutes); implement automatic upgrades for key rotationMinimizes window of exposure; rotates keys to invalidate compromised tokens quickly
StoragePrefer httpOnly Secure cookies or encrypted in-memory fields; avoid URLs and localStorageReduces risk of token theft via client-side vectors
ValidationEnforcer validates atjwt including issuer, audience, ft-date, and scopesPrevents misuse by enforcing server-side policy
LoggingMask tokens; log message IDs and non-sensitive metadata onlyMaintains traceability without exposing secrets
Key managementRotate signing keys automatically; track kid in config, apply upgradesPreserves trust chain and limits impact of key compromise
Interfaces and methodsDefine clear interfaces; encapsulate creating, parsing, verifying tokensImproves reuse and reduces accidental data exposure
Claims and valuesMap extracted values to controlled fields; maintain group-related mappingsEnables precise authorization while keeping data minimization
Audit and governanceMaintain an extended overview of usage, involved components, and config changesSupports compliance and rapid incident response

Troubleshooting and common migration blockers: practical fixes and FAQ

Run validations of the migration against a staging repository and curated endpoints, verify the hash checks, and inspect the keystore contents. Track latency in milliseconds and aim for under 150 milliseconds end-to-end to spot regressions early.

Blockers commonly arise from misaligned scopes, missing includes, and mismatches between queries, formats, and endpoints in the new path. Verify that category-specific flows map to the correct resources and that hostname preference matches the deployment target.

FAQ: What blocks the migration rollout? Answer: Align repositories access rules, update actions associated with sessions, and ensure the new authentication method is accepted by all endpoints.

Fix: update javadoc and client libraries with explicit guidance, remove reliance on query parameter authentication, and implement override logic for headers where needed. Ensure resources includes the new tokens and that keystore holds the required keys.

Operational steps: migrate formats for payloads, adjust scopes for calls, and validate that all requests include the new header token. Use options to select authentication mode and set user preference where applicable; test across endpoints, flows, and sessions.

Practical checks: run tests in telegin, review hash validations, and verify that multicast messages reach all linked endpoints. Confirm that times measured in milliseconds meet the target SLA, and that hostname resolves to the correct hosts.

FAQ: Should teams refactor each repository in small batches? Yes, begin with category-specific repositories, validate with a minimal set of queries, then scale. Keep linked resources up to date and monitor progress via dashboards that surface actions, endpoints, and scopes.