NetSuite SOAP and TBA Changes: What to Migrate Before 2027.1

MokuHub8 min read
netsuiteintegrationssuitetalkrestoauthsoap

NetSuite’s integration policy is changing in stages. The first stage is already in effect: new integrations should use SuiteTalk REST Web Services with OAuth 2.0. The next stage arrives with NetSuite 2027.1, when new SOAP and TBA integrations will no longer be allowed and NLAuth-based integrations will stop working.

This is not the same as an immediate shutdown of every existing SOAP integration. Oracle’s current documentation separates new-integration restrictions, authentication changes, and the later end of support for existing TBA usage. A migration plan should preserve those distinctions.

The short version

The current policy can be summarized as follows:

  • New integrations should use REST Web Services and OAuth 2.0 from NetSuite 2026.1.
  • From 2027.1, new SOAP integrations cannot be created.
  • From 2027.1, new integrations cannot use TBA.
  • From 2027.1, NLAuth integrations for RESTlets and related legacy use cases stop working.
  • From 2027.1, PKCE is required for new OAuth 2.0 Authorization Code Grant integrations, including private clients.
  • Existing SOAP and TBA integrations continue during the transition, and existing Integration Records may still be updated or modified until SOAP web services are fully removed.
  • Oracle currently describes the final TBA end of support as tentatively planned for 2028.1, excluding SuiteAnalytics Connect (ODBC/JDBC).
  • SOAP web services are a separate clock. Oracle states that with the 2028.2 release all endpoints will be disabled and SOAP-based integrations will stop working.

Those last two dates are the ones teams confuse most often. 2028.1 is the tentative end of support for Token-Based Authentication. 2028.2 is when the SOAP endpoints themselves are switched off. An integration can be affected by one, the other, or both, and the remediation is different in each case.

The 2028.1 date is also not a guaranteed retirement day. It is a planning signal that should trigger an inventory and migration programme, not a claim that an exact shutdown date has been announced.

What changes in 2027.1

New SOAP integrations are no longer allowed

SOAP Web Services has been the foundation of many NetSuite integrations, but Oracle identifies several reasons for moving to newer channels. SOAP does not expose every newer business object, uses an older technology model, and does not align with the current authentication direction.

Starting with 2027.1, a new integration cannot be built using SOAP Web Services. Existing integrations are not automatically disabled at that point.

That distinction matters for teams that maintain a working integration but have not yet migrated it. The integration may continue to run, but a new project, replacement connector, or new account connection should not be designed around SOAP.

New TBA integrations are no longer allowed

NetSuite 2027.1 also blocks creation of new integrations that use Token-Based Authentication. The restriction covers both the IssueToken endpoint and the three-step TBA authorization flow.

Existing TBA integrations are expected to continue until the final end of support for TBA. Oracle currently describes that final end of support as tentatively planned for 2028.1.

Teams should therefore avoid two opposite mistakes. Do not treat every existing TBA connection as already broken, but do not treat continued operation as evidence that TBA is a safe choice for new work.

NLAuth-based integrations stop working

NLAuth is the oldest authentication method in this transition. Oracle states that, as of 2027.1, integrations using NLAuth for RESTlets and unique legacy use cases will stop working.

The documentation notes an exception involving existing integrations that use the IssueToken endpoint. That exception should not be interpreted as permission to create new TBA integrations. The new-integration restriction and the NLAuth end-of-support notice describe different parts of the transition.

NLAuth has in fact been closing for years. NetSuite stopped supporting user credentials authentication for newly created RESTlets in 2021.1, so an NLAuth header today almost always belongs to an integration that predates that change and has never been revisited.

The three headers are easy to tell apart in a log or a connector configuration:

# NLAuth - stops working in 2027.1
Authorization: NLAuth nlauth_account=1234567,
  nlauth_email=integration%40example.com,
  nlauth_signature=,
  nlauth_role=3

# TBA - no new integrations from 2027.1, tentative end of support 2028.1
Authorization: OAuth realm="1234567", oauth_consumer_key="...",
  oauth_token="...", oauth_signature_method="HMAC-SHA256",
  oauth_timestamp="...", oauth_nonce="...", oauth_version="1.0",
  oauth_signature="..."

# OAuth 2.0 - the target
Authorization: Bearer

If an integration still sends NLAuth credentials, it should be treated as a migration candidate now.

PKCE becomes mandatory for new OAuth flows

PKCE was previously required for public clients and optional for private clients in the OAuth 2.0 Authorization Code Grant flow. From 2027.1, PKCE parameters are required for all new integrations using that flow.

Existing integrations without PKCE remain functional according to the current documentation. Even so, adding PKCE to an existing integration may be a sensible hardening task if the implementation and provider support it.

In practice PKCE adds one generated secret and two extra parameters. The client creates a random code_verifier, sends its SHA-256 hash on the authorization request, and sends the original verifier on the token request:

# authorization request
code_challenge=BASE64URL(SHA256(code_verifier))
code_challenge_method=S256

# token request
code_verifier=<the original random string>

The key planning rule is simple: build new OAuth Authorization Code Grant integrations with PKCE now. Do not wait for 2027.1 to discover that the callback flow, token exchange, or client library needs changes.

What should replace SOAP and TBA

Oracle positions SuiteTalk REST Web Services as the replacement for SOAP. OAuth 2.0 is the preferred authentication method for new integrations.

REST is not a magic protocol conversion. A SOAP operation, record type, field, search, or custom workflow may not map one-to-one to a REST request. Some integrations also depend on SOAP-specific batching, error handling, pagination, or data shapes.

For cases where REST Web Services cannot cover the required behavior, Oracle identifies SuiteScript RESTlets as an alternative. That does not mean every SOAP call should become a RESTlet. A RESTlet introduces an application surface that must be secured, versioned, monitored, and tested like any other code.

We wrote the step-by-step version of that move separately: what to migrate first, and in what order, including searches, batch operations, and the gaps that still have no clean answer.

A reasonable target architecture is:

  • REST Web Services for standard record operations;
  • OAuth 2.0 for authentication;
  • REST SuiteQL where the query use case is supported;
  • RESTlets only for business logic or operations that cannot be represented safely through standard REST APIs;
  • a documented compatibility layer during migration.

The migration inventory to build first

The most valuable first step is not changing credentials. It is building an inventory of what is actually running.

For every Integration Record or connected application, capture:

  • integration name and owner;
  • source and destination systems;
  • authentication method: SOAP, TBA, NLAuth, or OAuth 2.0;
  • SOAP endpoint or REST base URL;
  • NetSuite version assumptions;
  • record types and fields used;
  • search and SuiteQL usage;
  • batch or asynchronous processing;
  • custom records and custom fields;
  • RESTlets, User Events, or scheduled scripts involved;
  • error handling and retry behavior;
  • business process affected by a failed request;
  • last successful test date;
  • sandbox or Release Preview test status.

Authentication labels alone are not enough. A connector that uses TBA may be easy to move to OAuth 2.0 but still depend on a SOAP-only record or operation. A connector already using REST may still need an OAuth 2.0 change or a PKCE update.

A practical migration sequence

1. Find the highest-risk integrations

Prioritize integrations that post financial transactions, create or fulfill orders, update inventory, or control customer-facing processes. Next, prioritize connectors with no active owner, no sandbox test, or no vendor migration statement.

A low-volume integration can still be high risk if it is responsible for a critical month-end or tax process.

2. Separate protocol migration from authentication migration

A SOAP-to-REST change and a TBA-to-OAuth change are related, but they are not the same task. Track them separately.

For example:

  • SOAP + TBA requires both a transport/API assessment and an authentication change.
  • REST + TBA may require only an authentication migration, unless the endpoint or permissions also change.
  • REST + NLAuth requires an authentication migration before 2027.1.
  • REST + OAuth Authorization Code Grant should be checked for PKCE readiness.

This separation makes testing more precise and reduces the risk of declaring a migration complete after changing only the token flow.

3. Test business outcomes, not only HTTP responses

A successful REST request proves that the server accepted the request. It does not prove that the integration produced the same business result as the SOAP version.

For each critical flow, compare:

  • created or updated records;
  • field values and defaults;
  • taxes and currency behavior;
  • subsidiary and permission context;
  • links between transactions;
  • duplicate prevention;
  • partial failure behavior;
  • retry behavior;
  • audit trail and system notes;
  • downstream notifications.

A migration is complete only when the business process has been exercised in a safe environment and the result has been reconciled.

4. Add a cutover and rollback plan

Keep the old path available during a controlled overlap where the business process allows it. Define how to prevent duplicate writes if both paths are active. Record the last successful run on the old integration and the first reconciled run on the new one.

Do not make a credential change in production without knowing which process will detect a failed authentication, who owns the rollback, and whether the old credential remains valid.

What developers should check now

Developers should review:

  • SOAP client libraries and endpoint versions;
  • TBA IssueToken calls and three-step authorization flows;
  • NLAuth headers used by RESTlets;
  • OAuth Authorization Code Grant callbacks;
  • PKCE code verifier and challenge handling;
  • REST record and field coverage;
  • REST SuiteQL support for existing queries;
  • batch ordering and idempotency;
  • rate limits, governance, retries, and pagination;
  • permission differences between the old and new Integration Records.

The migration should also be tested against the account’s target NetSuite release. Oracle is explicit that full parity should not be assumed: some legacy SOAP functionality is deliberately not exposed in REST because it should no longer be used, and Oracle describes parity as something that will be significantly improved in upcoming releases rather than something already complete.

The operational takeaway

NetSuite 2027.1 is not the day when every existing SOAP and TBA integration suddenly disappears. It is the point at which new work must follow the modern path, NLAuth-based integrations become an immediate problem, and OAuth Authorization Code Grant implementations need PKCE for new integrations.

The right response is a measured inventory now, followed by a migration plan that separates authentication, API coverage, and business-process verification. Move new development to REST and OAuth 2.0, and build PKCE into new authorization-code flows.

Then hold the two end dates apart. If the integration authenticates with TBA, the planning deadline is the tentative 2028.1 end of support, with SuiteAnalytics Connect (ODBC/JDBC) excluded. If it calls SOAP web services, the hard date is 2028.2, when the endpoints are switched off. A connector that does both inherits the earlier of the two, and neither is a reason to wait.

Sources

[1] SOAP Removal Plans FAQ

[2] NetSuite Authentication changes in 2026.2

[3] NetSuite Version 2026.2 release index