NetSuite TBA to OAuth 2.0: Migration Guide Before 2027.1

NetSuite's Token-Based Authentication (TBA) is OAuth 1.0 with a NetSuite twist: every request is signed with a consumer key and secret plus a token ID and secret. It has been the default way to connect integrations to NetSuite for a decade. Oracle is retiring it in two steps, and the first one lands in 2027.1.

Direct answer: From NetSuite 2027.1 you can no longer create new integrations that use TBA, through the IssueToken endpoint or the three-step TBA flow. Existing TBA integrations keep working until full end of support, which Oracle gives as 2028.2. The same release ends NLAuth for RESTlets and makes PKCE mandatory for new OAuth 2.0 authorization code integrations. For server-to-server integrations, migrate to the OAuth 2.0 client credentials (machine-to-machine) flow with a certificate. The practical breaking point comes earlier than 2028.2: after 2027.1, a sandbox refresh or a new environment that needs a new TBA token cannot get one.

Checked on November 5, 2026 against Oracle's 2026.2 release notes and the NetSuite help center, linked at the end.

---

The dates

NetSuite ships two releases a year, so 2027.1 is the first half of 2027 and 2028.2 is the second half of 2028. Each account moves on its own upgrade date inside the release window.

For the release context, see our 2026.2 notes for developers and IT architects.

Why "existing integrations keep working" is not the whole story

The 2028.2 date makes it tempting to wait. Three things make 2027.1 the real deadline for most accounts:

1. Sandbox refreshes. After a sandbox refresh, integrations pointed at the sandbox need new tokens. NetSuite developers have pointed out the consequence: after 2027.1, a refreshed sandbox cannot get new TBA tokens, so every integration you test in sandbox has to be on OAuth 2.0 first.
2. New environments and new vendors. A new subsidiary integration, a new 3PL, a new iPaaS flow, a new Release Preview account: none of them can be set up on TBA after 2027.1.
3. Token rotation. If your security policy rotates tokens, or an employee who owned a token leaves and the token is revoked, you cannot issue a replacement TBA token.

In practice: anything you will need to re-authenticate, test in sandbox or clone after 2027.1 has to be on OAuth 2.0 before 2027.1.

Which OAuth 2.0 flow to use

NetSuite supports two OAuth 2.0 grants. Pick by who is on the other end.

Most TBA integrations are server-to-server, so most migrations go to client credentials.

Client credentials setup, step by step

1. Enable OAuth 2.0. Setup > Company > Enable Features > SuiteCloud > Manage Authentication > OAuth 2.0.
2. Create or update the integration record. Setup > Integration > Manage Integrations. On the Authentication subtab check Client Credentials (Machine to Machine) Grant and the scopes the integration needs: RESTlets, REST Web Services or SuiteAnalytics Connect. Copy the client ID and secret when they show; NetSuite shows them once. You can keep the TBA boxes checked during the transition.
3. Generate a key pair. NetSuite accepts an x.509 certificate (.cer, .pem or .crt) with an RSA key of 3072 or 4096 bits, or an EC key of 256, 384 or 521 bits. Maximum validity is two years. Oracle's SuiteCloud CLI documentation requires RSA, so use RSA if the CLI is involved.
4. Map the certificate. Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup > Create New. Choose the entity (user), the role and the application, and upload the public certificate. Keep the certificate ID.
5. Request tokens. Your integration builds a JWT with the certificate ID as kid, signs it with the private key, and posts it to the token endpoint. The response is an access token valid for 60 minutes.
6. Swap the auth layer, not the integration. Every request now carries Authorization: Bearer <access token> instead of the OAuth 1.0 signature. Endpoints, payloads and SuiteQL stay the same.

Rules that catch teams the first time:

• One certificate per combination of integration record, role and entity. A second role or user needs a second certificate.
• Up to five active certificates per combination, so you can rotate before expiry. NetSuite emails administrators two months, one month and 14 days before a certificate expires.
• The mapping is not copied to other production, sandbox or Release Preview accounts, and a sandbox refresh clears it. Add "re-map M2M certificates" to your sandbox refresh checklist.
• Only an administrator or a user with the OAuth 2.0 Authorized Applications Management permission can create or revoke mappings.

A migration plan that fits in one quarter

Week 1 to 2: inventory. List every integration record with TBA checked (Setup > Integration > Manage Integrations) and every access token (Setup > Users/Roles > Access Tokens). For each, write down the system on the other end, who owns it, the role it runs as and whether the vendor already supports OAuth 2.0. Search your RESTlet callers for NLAuth headers too: those break in 2027.1, not 2028.2.

Week 2 to 3: sort by owner.

• Vendor-managed connectors (Celigo, Boomi, MuleSoft, 3PLs, payment and tax apps): ask the vendor for their OAuth 2.0 path and date. Most iPaaS connectors already support it; the work is reconnecting.
• Your own code: middleware, scripts, scheduled jobs. These need the auth layer rewritten as above.
• Dead integrations: tokens nobody can name. Revoke them; it is a security win on its own.

Week 3 to 8: migrate in sandbox, then production. One integration at a time, with the OAuth 2.0 version running beside the TBA one until it is proven. Keep the TBA token until you switch, then revoke it.

Week 8 onward: lock it in. Update your sandbox refresh runbook, put certificate expiry dates on a calendar and make OAuth 2.0 the only option for anything new.

Pair it with the SuiteScript 2.1 work

The same 2028.2 release that ends TBA support also stops SuiteScript 1.0, 2.0 and 2.x scripts. Many RESTlets that external systems call through TBA are old SuiteScript, so the two migrations touch the same files. Doing them together saves a second round of testing. See what the SuiteScript deadline costs if you wait and our REST API guide for the endpoint side.

---

Sources

• NetSuite 2026.2 for developers and IT architects: the authentication changes, with links to Oracle's release notes
• OAuth 2.0 Client Credentials (M2M) Setup (Oracle NetSuite help center)
• Create Integration Records for Applications to Use OAuth 2.0 (Oracle NetSuite help center)
• Refresh Token POST Request to the Token Endpoint (Oracle NetSuite help center)
• Using SuiteAnalytics Connect with OAuth 2.0 (Oracle Developers blog)

What clients ask before signing

When does NetSuite stop supporting Token-Based Authentication?expand_more

Is NetSuite TBA the same as OAuth 1.0?expand_more

Which OAuth 2.0 flow replaces TBA in NetSuite?expand_more

How long does a NetSuite OAuth 2.0 access token last?expand_more

Does a sandbox refresh break OAuth 2.0 integrations?expand_more

Do I need to migrate integrations from Celigo or other connectors?expand_more