NetSuite TBA to OAuth 2.0 Migration Guide (2027.1 Cutoff)

Oracle's NetSuite 2026.2 authentication release note, last updated September 21, 2026, says: "As of NetSuite 2027.1, you won't be able to create new integrations that use TBA for authentication." That starts the clock on a NetSuite TBA to OAuth 2.0 migration for anything built on token-based authentication (TBA). Integrations already running on TBA keep working until support ends, which Oracle tentatively puts at release 2028.2. If you ship one NetSuite integration into many customer accounts, the move is bigger than a new auth header: SOAP integrations need a new transport, every OAuth 2.0 flow adds a recurring per-account cost TBA didn't have, and Oracle hasn't said whether a customer who installs your existing integration record after the cutoff counts as a new integration.

Oracle's dates for TBA, SOAP and OAuth 2.0

Oracle's TBA end-of-support page states the scope: "Starting in NetSuite 2027.1, you will no longer be able to create new integrations that use TBA for SOAP and REST web services, and RESTlets." Support for existing integrations ends later, "tentatively NetSuite 2028.2," and that end date excludes SuiteAnalytics Connect (ODBC/JDBC). The release note adds that the block covers "both the IssueToken endpoint, and the three-step TBA authorization flow." Oracle's TBA overview drops the "tentatively" and says support ends in 2028.2. Plan for that date as if it were firm.

Release 2027.1 changes more than TBA. The same release note makes PKCE parameters required for every new integration that uses the OAuth 2.0 authorization code grant (existing ones without PKCE keep working), stops integrations that use NLAuth (Oracle excludes existing integrations that call the IssueToken endpoint), and turns on the Require 2FA for All Roles feature automatically, with an option for administrators to disable it. In 2028.2, the SOAP web services overview says SOAP "will no longer be available in NetSuite and existing SOAP integrations with NetSuite will stop working." Oracle's SOAP removal FAQ lists which SOAP endpoints stay supported in between, and our NetSuite REST API guide covers the REST side you're moving to.

A new integration means a new integration record

Oracle's docs never define "new integration" beyond the integration record. Before anyone can authorize an OAuth 2.0 application, "an integration record must be created," per the integration record page, and Oracle tells you to create a separate record for each application. Its SOAP removal FAQ says that "existing Integration Records for integrations using SOAP web services and TBA may still be updated or modified until SOAP web services are fully removed." For an in-house integration with one record in one account, the reading is clear enough: a record created before 2027.1 is an existing integration, though Oracle doesn't say so in those words.

Distributed integrations are less clear. Oracle lets you bundle an integration record for install in other accounts or configure it to install automatically. An installed record is "considered to be owned by a different NetSuite account." The customer can edit only its Note and State fields (Oracle's OAuth 2.0 record page adds the consent policy to the account-specific fields), while the owner controls the rest, "including the permitted authentication options," and "Changes made by the owner are automatically synced to your account."

The docs don't say whether a customer who installs your pre-2027.1 record after 2027.1 and then issues TBA tokens on it has created a new integration. They also don't say whether new tokens can still be issued on an existing record once the cutoff passes. If you distribute a record, ask Oracle in writing, through a support case or your partner manager, and until you have an answer, assume every customer who connects after 2027.1 needs OAuth 2.0. Because the owner's authentication settings sync to installed copies, adding OAuth 2.0 to the record you already distribute should reach every installed account. Oracle documents the sync but doesn't walk through this migration case, so test it in a sandbox first.

SOAP with TBA is a rewrite

OAuth 2.0 "cannot be used with SOAP web services," per Oracle's TBA overview, and the OAuth 2.0 chapter limits the feature to RESTlets, REST web services and SuiteAnalytics Connect. On an integration record, Oracle's TBA integration record page allows only the TBA and user credentials boxes for SOAP. A SOAP integration on TBA therefore has no auth-only migration path. Its calls move to REST web services or RESTlets, and its authentication moves to OAuth 2.0, in the same project.

Oracle's FAQ warns that "You should not expect 100% parity of REST with SOAP" and points to SuiteScript RESTlets when REST lacks an object or method. Write any new RESTlet in SuiteScript 2.1: Oracle expects to remove support for older SuiteScript versions in the same 2028.2 release, and our SuiteScript 1.0 to 2.1 migration guide covers converting the scripts you already have. Oracle publishes a SOAP to REST upgrade guide that maps operations, and our NetSuite SOAP API guide documents the surface you're leaving. Integrations that already call REST or RESTlets with TBA have the smaller job: same endpoints, new authentication. The FAQ says only new integrations must use OAuth 2.0 from 2027.1, but the 2028.2 end of support takes that slack away.

Picking a NetSuite OAuth 2.0 flow for multi-tenant sync

Oracle's migration guidance gives one rule. The client credentials flow is "Ideal for background services and server-side workloads that don't require a user to log in and interact with them," and the authorization code grant is "Ideal for integrations that require a user to grant access to the application." For a SaaS product syncing many tenants, the useful comparison is what each option costs you per customer account.

With the authorization code grant and a confidential client, a user signs in to NetSuite, picks a role and consents. The access token lasts 60 minutes and the refresh token seven days, per Oracle's token request page. A refresh returns a new access token and no new refresh token, so when the refresh token expires the token endpoint returns invalid_grant and the refresh docs send you back to step one. For a nightly sync, a person in each customer account has to sign in and re-authorize every week. Developers have hit that wall since at least May 2020, when a NetSuite Professionals thread asked whether OAuth 2.0 could serve long-term integrations, and a 2023 Stack Overflow question reports that prompt=none didn't avoid the consent page.

Public clients have no client secret. Oracle's integration record docs say that "if you distribute your integration outside your account, you don't have control over confidentiality of its client secret. In such case, always use OAuth 2.0 with public clients." Each refresh token is one-time and valid for 48 hours by default (configurable from 1 to 720), and each refresh returns a new pair. A second field, Maximum Time For Token Rotation (default 168 hours, maximum 720), sets when the user has to authenticate again. Your scheduler has to refresh before each token lapses, and a missed window means the user signs in again.

Client credentials, which Oracle also calls machine-to-machine (M2M), needs no user at all, and public clients can't use it. An administrator in each customer account maps your integration record to an entity, a role and your public certificate, per the M2M setup page. Your service signs a JWT with the private key and trades it for a 60-minute access token, with no refresh token, per the client credentials token docs. The certificate conditions set the operational load: RSA keys of 3072 or 4096 bits or EC keys of 256, 384 or 521 bits, a validity of at most two years, and each certificate can serve only one combination of integration record, role and entity. NetSuite emails administrators two months, one month and 14 days before a certificate expires. Each combination can hold up to five active certificates, which lets you upload the next one before the current one lapses, and Oracle offers a certificate rotation endpoint for doing that in code.

Onboarding changes with any of the three. "Unlike the TBA tokens, you can't create OAuth 2.0 authorized applications directly in the UI," per Oracle's authorized applications page. If your setup guide today has an administrator create NetSuite API credentials and paste a token ID and secret into your app, that step has no OAuth 2.0 equivalent. A user consents in a browser, or an administrator uploads your certificate.

For background sync across many accounts, client credentials is the option that doesn't put a person in each account on a weekly or monthly clock, and you pay for it with certificate tracking per tenant. Keep the authorization code grant for features where a user is present to sign in.

Setup the customer's administrator does in each account

Oracle's administrator checklist starts with the feature, then roles and users, then the integration record. In each customer account that means:

• Enable OAuth 2.0 under Setup > Company > Enable Features > SuiteCloud > Manage Authentication. RESTlets also need Client SuiteScript and Server SuiteScript, per Oracle's feature page.
• Give the integration's role the "Log in using OAuth 2.0 Access Tokens" permission. A role with only OAuth 2.0 Authorized Applications Management can't call REST web services, RESTlets or SuiteAnalytics Connect, per the permissions page.
• Set the consent policy on the integration record (Always Ask, the default, Never Ask or Ask First Time). On an installed record that value belongs to the customer's account, not to you.
• For client credentials, create the certificate mapping. Only an administrator or a role with OAuth 2.0 Authorized Applications Management can do it, and that permission requires two-factor authentication.

Send the authorization request to the account-specific domain, <accountID>.app.netsuite.com, or to system.netsuite.com when you don't know the account ID yet. The redirect back carries a company parameter with the account ID, per Oracle's step one page. The person who consents logs in to NetSuite, and from 2027.1 that login has two-factor authentication on for all roles unless the customer's administrator turns it off.

Moving accounts from NetSuite TBA to OAuth 2.0 one at a time

A REST integration record can carry both: "For accessing REST web services, both the Token-based Authentication (TBA) and the OAuth 2.0 boxes can be checked," per Oracle's TBA integration record page, and RESTlet records allow TBA, OAuth 2.0 and user credentials together. That lets you keep TBA connections running while you move customers to OAuth 2.0 one account at a time.

Oracle's migration preparation page describes how a customer finds TBA usage: a Login Audit Trail saved search where "Token-based Access Token Name" is not empty, limited to the last 12 months and grouped by "Token-based Application Name." To test without TBA, an owner can clear the TBA boxes on a record or set its State to Blocked, and Oracle notes that "both these options only work with integration records that you own." Its migration and testing page asks for sandbox accounts first, a check of roles and permissions, end-to-end tests of scheduled jobs, imports, exports, reporting refreshes and downstream dependencies, and close monitoring after the switch.

Sandboxes need their own pass. OAuth 2.0 authorizations aren't copied from production to a sandbox, and the M2M setup "gets cleared" each time a sandbox is refreshed, so every refresh means a new consent or a new certificate mapping in that sandbox.

Problems developers have reported

Oracle's SuiteCloud CLI uses the client credentials flow for CI logins, but in March 2026 an Oracle maintainer confirmed that "the SuiteCloud CLI documentation explicitly states that the certificate must be RSA," while the general certificate page also lists EC keys. An earlier issue from January 2025 shows a certificate ID starting with a hyphen breaking the CLI's setup command, and Oracle's advice there was to regenerate the key pair.

Third-party docs lag behind Oracle's: AWS's Glue connector limitations page still says public-client refresh tokens last three hours, against the 48-hour default in Oracle's current integration record docs. Take token lifetimes from Oracle's pages and confirm them in a sandbox.

Migrating with Apideck

Apideck's NetSuite connector authenticates with TBA today. Oracle's switch to OAuth 2.0, and its move from SOAP to REST, is work Apideck does once, in the connector, for every connected account. Your code keeps calling the same Apideck Accounting API: you won't rewrite request signing, rotate integration records account by account, or move SOAP calls to REST. What a customer may still need to do is re-authorize their NetSuite connection or have an administrator approve the new OAuth 2.0 access when Apideck asks. We haven't set a date for that switch yet, and we'll tell connected customers before anything changes for them.

If you run your own NetSuite integration, start the inventory now: list every integration record you own or distribute, mark which ones call SOAP, and open the "new integration" question with Oracle before 2027.1 rather than after. If NetSuite is one of several accounting systems your customers use, connect it through Apideck's NetSuite API integration and leave the auth migration to the connector.