NetSuite TBA Is Being Deprecated: Migrating Integrations to OAuth 2.0

If you have integrations calling NetSuite using Token-Based Authentication, you have probably heard that something is changing. What actually changes, on what date, and whether you need to act now are three separate questions. The answers depend on whether you are building something new or maintaining something existing, and which protocol it runs on.

This post covers the verified timeline from Oracle, explains who needs to act before 2027.1 and who has more runway, and sets out the technical requirements for OAuth 2.0 so you can plan the migration properly. It is part of the broader NetSuite integration guide, which covers how the integration surfaces fit together.

What TBA is and why Oracle is moving on

Token-Based Authentication is NetSuite's implementation of OAuth 1.0a: a consumer key, consumer secret, token ID, and token secret, signed per-request using HMAC-SHA256. It was the standard external integration auth method for years.

OAuth 2.0 is the current industry standard across Oracle's product suite. Where TBA uses per-request signatures, OAuth 2.0 issues short-lived bearer tokens. It has two distinct grant types for machine-to-machine versus user-delegated access, and uses modern key standards. Oracle's stated reasons for the shift are consistency with authentication across the rest of its product line and alignment with current security standards.

The timeline

Three dates matter:

2026.1 (now): All new integrations should use REST Web Services with OAuth 2.0. This is guidance rather than a hard block, but the direction is clear.

2027.1: New Token-Based Authentication integrations are blocked. You will not be able to create new Integration Records for integrations using TBA. This applies to SOAP, REST, and RESTlets. Existing Integration Records can still be updated, but new ones require OAuth 2.0.

2028.2: SOAP is removed entirely. All SOAP integrations stop working regardless of auth method.

Source: Oracle NetSuite release notes and web services documentation, verified July 2026. Confirm against the current release notes when you plan; the dates are Oracle's to move.

Who needs to act, and when

The urgency depends on what you are building versus what you are already running.

Building something new: Use REST Web Services with OAuth 2.0. Starting a new TBA integration now means migrating it before 2027.1.

Maintaining an existing REST integration using TBA: No forced deadline yet. Oracle has confirmed that existing REST+TBA integrations continue working past 2027.1. Plan the migration, but it is not mandatory for existing integrations.

Maintaining a SOAP integration using TBA: Hard deadline at 2028.2. SOAP is removed entirely at that point. Plan the move to REST+OAuth 2.0; do not leave it until the final year.

Calling a RESTlet from an external system using TBA: No forced deadline for the existing integration, and no need to abandon the RESTlet either: RESTlets support OAuth 2.0 directly. Enable the RESTlets scope on the Integration Record, add the "Log in using OAuth 2.0 Access Tokens" permission to the role, and move the calling system to bearer tokens; the RESTlet script itself does not change. Alternatively, if the RESTlet only does standard CRUD, replacing it with a REST Web Services call removes custom code at the same time.

Finding TBA in your account

Go to Setup > Integration > Manage Integrations and filter for integrations where Token-Based Authentication is enabled. This gives you the full list: how many are TBA-based, which are active, and who created them.

Then go to Setup > Users/Roles > Access Tokens. This shows every token pair in the account, which integration it belongs to, and the associated role and user. Tokens with no activity in the last six months are worth investigating before assuming everything needs migrating; some may belong to integrations that are no longer in use.

Choosing the OAuth 2.0 grant type

OAuth 2.0 has two grant types in NetSuite. The choice is usually clear.

Client Credentials is for machine-to-machine: no user interaction, no consent flow, suited for automated syncs and batch processes. This is the right choice for most server-side integrations that currently use TBA.

Authorization Code is for user-delegated access. A real user approves the connection, the token is scoped to their identity, and the refresh token expires after 7 days, so the user periodically reauthorises. Use this when the integration needs to act as a specific employee rather than as a system account.

Technical requirements

These are the points where OAuth 2.0 setups most commonly fail. Check them before generating keys or writing code.

Key type. NetSuite requires RSA-PSS keys of 3072 or 4096 bits, or EC keys (256, 384, or 521 bits). RSA PKCS#1 v1.5 is not supported for the JWT client credentials flow and will reject token requests without a helpful error message. If your integration library generates PKCS#1 keys by default, change this first.

Key storage. Private keys must not appear in SuiteScript code, script parameters, or custom fields. Use NetSuite's API Secrets management at Setup > Company > Preferences > API Secrets. The key is referenced by its script ID at runtime; it is never embedded.

Integration Record. Every OAuth 2.0 integration needs an Integration Record with the appropriate grant type enabled. For a Client Credentials integration, the SDF XML looks like this:

<integration scriptid="custinteg_myapp_oauth">
    <name>My Integration OAuth</name>
    <state>ENABLED</state>
    <oauthclientcredentialsgrantenabled>T</oauthclientcredentialsgrantenabled>
</integration>

If you are shipping a SuiteApp, include this record in the bundle. Customers should not have to create it manually.

Concurrency. REST Web Services concurrency is account-level, set by your service tier, and increased by each SuiteCloud Plus licence. Check your account's limit at Setup > Integration > Integration Governance. HTTP 429 means you have hit it. Implement exponential back-off and retry; do not hammer the endpoint.

Token expiry. Access tokens are short-lived (60 minutes). Client Credentials has no refresh token: the integration requests a new access token with a signed JWT. Authorization Code uses a refresh token that expires after 7 days; your integration needs to handle both the refresh flow and the eventual reauthorisation. An invalid_grant error means the token or refresh token is no longer valid and the flow needs to restart.

Token invalidation and the silent failure connection

TBA token invalidation is one of the named causes of silent integration failures: a token pair gets revoked (because a user's role changes, an admin rotates credentials, or the integration is modified in NetSuite), and the integration starts producing auth errors that look, to the system on the other side, like empty responses or connection timeouts rather than explicit authentication failures.

The silent failure diagnosis post covers how to identify this in your execution logs and what to put in place to alert on auth failures before they become data gaps.

OAuth 2.0 does not eliminate this class of problem (tokens expire and keys can be revoked), but the failure mode is more explicit. A 401 from REST Web Services is a clean signal. A silently dropped response from a SOAP connection is not.

Frequently asked questions

Do my existing TBA integrations break when the 2027.1 deadline arrives?

No, not automatically. The 2027.1 restriction blocks new integrations from using TBA; existing integrations continue working. The hard cutoff is 2028.2, when SOAP is removed entirely and any SOAP integration stops working. Existing REST-based integrations using TBA do not have a forced migration deadline, though OAuth 2.0 is the direction Oracle is pushing.

Does TBA still work for calling NetSuite RESTlets from external systems?

Yes, existing TBA-based RESTlet integrations keep working. But RESTlets also support OAuth 2.0 directly, so migrating does not mean abandoning the RESTlet: enable the RESTlets scope on the integration record, give the role the "Log in using OAuth 2.0 Access Tokens" permission, and switch the calling system to bearer tokens. From 2027.1 new integrations cannot use TBA, so new RESTlet integrations should start on OAuth 2.0.

What OAuth 2.0 grant type should I use for a server-to-server integration?

Client Credentials. This is the machine-to-machine grant: no user consent flow, tokens requested directly with a signed JWT, suited for batch processes and automated syncs. Authorization Code is for user-delegated access where a real user needs to approve the integration, for example a web application connecting on behalf of a specific employee.

Why does my OAuth 2.0 token request keep failing after I set everything up?

The most common reason is key type. NetSuite requires RSA-PSS keys of 3072 or 4096 bits, or EC keys (256, 384, or 521 bits). RSA PKCS#1 v1.5 is not supported for the JWT client credentials flow and will fail token requests without a clear error. Check the key algorithm your integration library is using before debugging anything else.

If you have an integration that needs migrating off TBA, or you are building a new one and want the OAuth 2.0 setup right first time, the technical review call is the starting point.