NetSuite TBA (OAuth 1.0a) vs OAuth 2.0: Differences, Deprecation & Migration

TL;DR

• Bottom line: Use OAuth 2.0 for all new NetSuite integrations. TBA (OAuth 1.0a) is legacy — no new TBA integrations allowed after 2027.1. The one exception: SOAP web services still require TBA because OAuth 2.0 does not support SOAP. [src1, src2]
• Key limit: OAuth 2.0 cannot authenticate SOAP web services calls. If you depend on SOAP, you must use TBA until you migrate to REST (SOAP fully disabled at 2028.2). [src1, src4]
• Watch out for: OAuth 2.0 M2M (client credentials) requires X.509 certificate upload and per-account setup — the M2M mapping is NOT copied between production, sandbox, or Release Preview accounts. [src3]
• Best for: Deciding which authentication method to use for a NetSuite integration, understanding the deprecation timeline, and planning TBA-to-OAuth 2.0 migration.
• Authentication: OAuth 2.0 authorization code flow for user-context apps; OAuth 2.0 client credentials (M2M) with certificate for server-to-server; TBA for SOAP-only legacy. [src1, src2]

System Profile

This card covers authentication methods for Oracle NetSuite's API surfaces. NetSuite supports two primary programmatic authentication protocols: Token-Based Authentication (TBA, built on OAuth 1.0a) and OAuth 2.0. The choice between them depends on the API surface, integration pattern, and timeline — TBA is being phased out in favor of OAuth 2.0 across all API surfaces except SOAP (which itself is being deprecated). [src1, src2]

API Surfaces & Capabilities

Not all API surfaces support both authentication methods. This is the single most important table for deciding which auth method to use. [src1, src2, src6]

Rate Limits & Quotas

Authentication method does not directly change API rate limits — limits are governed by the API surface and account tier. However, token lifetime and refresh behavior differ significantly. [src1, src2]

Token Lifetime Comparison

Per-Request Overhead

Authentication

Flow Comparison

TBA Setup (OAuth 1.0a)

1. Enable features: Setup > Company > Enable Features > SuiteCloud > Token-Based Authentication. [src2]
2. Create integration record: Setup > Integration > Manage Integrations > New. Check "Token-Based Authentication". Note Consumer Key and Consumer Secret. [src2]
3. Create access token: Setup > Users/Roles > Access Tokens > New. Select integration, user, role. Note Token ID and Token Secret. [src2]
4. Sign requests: Each API request must include an OAuth 1.0a Authorization header with HMAC-SHA256 signature computed from consumer key, consumer secret, token ID, token secret, nonce, and timestamp. [src2, src6]

OAuth 2.0 Authorization Code Setup

1. Enable features: Setup > Company > Enable Features > SuiteCloud > OAuth 2.0 + REST Web Services. [src1]
2. Create integration record: Check "Authorization Code Grant". Enter Redirect URI. Note Client ID and Client Secret. [src1]
3. Authorization: Redirect user to NetSuite authorize endpoint with client_id, redirect_uri, scope, response_type=code, state. [src1]
4. Token exchange: POST to token endpoint with grant_type=authorization_code. [src1]
5. Refresh: POST with grant_type=refresh_token when access token expires. [src1]

OAuth 2.0 Client Credentials (M2M) Setup

1. Enable features: Same as authorization code — OAuth 2.0 + REST Web Services. [src1]
2. Create integration record: Check "Client Credentials (Machine to Machine) Grant". Note Client ID. [src3]
3. Generate certificate: openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -nodes -days 730. Keep key.pem private. [src3]
4. Create M2M mapping: Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup > Create New. Select entity, role, application. Upload cert.pem. Save. Note Certificate ID. [src3]
5. Get token: POST to token endpoint with grant_type=client_credentials and JWT assertion signed with private key. [src3]

Authentication Gotchas

• M2M setup is per-account: The entity/role/certificate mapping is NOT copied to sandbox or Release Preview. Must re-create in each account. Sandbox setup is cleared on refresh. [src3]
• Max 5 active certificates: Each integration record can have at most 5 active certificates for M2M. Revoked and expired do not count. [src3]
• TBA tokens survive password rotation: TBA tokens are not affected by password policies. Security advantage (no breakage) but also a risk (tokens persist indefinitely). [src2, src6]
• 2FA bypass: Both TBA and OAuth 2.0 bypass UI-level 2FA since they operate at the API level. Role must have "Log in using Access Tokens" permission. [src6]
• Token endpoint URL varies by account: Base URL uses your account ID (e.g., https://TSTDRV1234567.suitetalk.api.netsuite.com). Getting this wrong is the #1 auth failure. [src1]

Constraints

• OAuth 2.0 cannot authenticate SOAP calls: If you have SOAP-dependent integrations, you must use TBA until you migrate to REST. No workaround. [src1, src4]
• 2027.1 hard cutoff for new TBA: After 2027.1, no new integration records can enable TBA for SOAP, REST, or RESTlets. Existing TBA integrations continue working. [src2]
• SOAP fully disabled at 2028.2: All SOAP endpoints turned off. Must be on REST + OAuth 2.0 by then. [src4]
• M2M certificate format: Public key must be X.509 (.cer, .pem, .crt) with RSA 3072 or 4096 bit. Smaller keys rejected. [src3]
• SuiteCloud SDK requires OAuth 2.0: As of SDK 24.2, TBA no longer supported for SDF connections. [src8]
• M2M uses JWT assertion, not client secret: Different from standard OAuth 2.0 client credentials. You sign a JWT with your private key — no client_secret parameter. [src3]

Integration Pattern Decision Tree

START -- New NetSuite integration, choosing auth method
|
+-- Which API surface?
|   |
|   +-- SOAP Web Services?
|   |   +-- YES --> TBA is required (OAuth 2.0 not supported for SOAP)
|   |   |   +-- Is this a new integration?
|   |   |       +-- YES --> STOP. Do NOT build new SOAP integrations.
|   |   |       |   Migrate to REST + OAuth 2.0 instead. SOAP sunsets 2028.2.
|   |   |       +-- NO (existing) --> Keep TBA, plan REST migration before 2028.2
|   |   +-- NO --> Continue to next question
|   |
|   +-- REST Web Services or RESTlets?
|   |   +-- Is this server-to-server (no user context)?
|   |   |   +-- YES --> OAuth 2.0 Client Credentials (M2M)
|   |   |   |   Requirements: X.509 cert, M2M mapping per account
|   |   |   +-- NO --> OAuth 2.0 Authorization Code
|   |   |   |   Requirements: Redirect URI, user consent flow
|   |
|   +-- SuiteAnalytics Connect (ODBC/JDBC)?
|   |   +-- OAuth 2.0 (resolves 2FA issues with legacy passwords)
|   |
|   +-- SuiteCloud SDK / SDF?
|       +-- OAuth 2.0 (mandatory since SDK 24.2)
|
+-- Migrating existing TBA integration?
    +-- REST/RESTlet? --> Switch to OAuth 2.0 M2M or Auth Code
    +-- SOAP? --> Migrate to REST first, then OAuth 2.0
    +-- Timeline: Complete before 2027.1 (new TBA blocked)

Quick Reference

TBA vs OAuth 2.0 — Side-by-Side Comparison

Deprecation Timeline

Step-by-Step Integration Guide

1. Determine your authentication method

Use the decision tree above. For new server-to-server integrations, OAuth 2.0 M2M is the recommended path. [src1]

Verify: Check Setup > Integration > Manage Integrations to confirm OAuth 2.0 and REST Web Services are enabled.

2. Set up OAuth 2.0 M2M authentication

Generate an RSA 4096-bit X.509 certificate and configure the M2M mapping. [src3]

# Generate RSA 4096-bit key pair and self-signed X.509 certificate (valid 2 years)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -nodes -days 730 \
  -subj "/CN=netsuite-integration/O=YourCompany"

Verify: openssl x509 -in cert.pem -text -noout | grep "Public-Key" → expected: Public-Key: (4096 bit)

3. Create integration record and M2M mapping

In NetSuite UI, create the integration record with M2M grant and map entity/role/certificate. [src3]

Verify: The M2M Setup page shows your mapping as "Active".

4. Request an access token using JWT assertion

Build a JWT, sign it with your private key, and exchange it at the token endpoint. [src3]

# Input:  client_id, certificate_id, account_id, private key (key.pem)
# Output: access_token (valid 60 minutes)

import jwt
import time
import requests

ACCOUNT_ID = "TSTDRV1234567"
CLIENT_ID = "your-client-id-from-integration-record"
CERTIFICATE_ID = "your-certificate-id-from-m2m-setup"
TOKEN_URL = f"https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token"

with open("key.pem", "r") as f:
    private_key = f.read()

now = int(time.time())
payload = {
    "iss": CLIENT_ID,
    "scope": "rest_webservices",
    "aud": TOKEN_URL,
    "exp": now + 300,
    "iat": now,
}
assertion = jwt.encode(payload, private_key, algorithm="RS256",
                       headers={"kid": CERTIFICATE_ID})

resp = requests.post(TOKEN_URL, data={
    "grant_type": "client_credentials",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": assertion,
})
resp.raise_for_status()
access_token = resp.json()["access_token"]

Verify: Response contains access_token and expires_in: 3600.

5. Make an authenticated API call

Use the bearer token to call NetSuite REST Web Services. [src1]

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}
response = requests.get(
    f"https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/record/v1/customer/123",
    headers=headers
)
print(response.json())

Verify: HTTP 200 response with customer record JSON.

Code Examples

Python: TBA (OAuth 1.0a) request signing

# Input:  consumer_key, consumer_secret, token_id, token_secret, account_id
# Output: Authenticated REST API call using TBA

import requests
from requests_oauthlib import OAuth1

ACCOUNT_ID = "TSTDRV1234567"
BASE_URL = f"https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/record/v1"

auth = OAuth1(
    client_key="your-consumer-key",
    client_secret="your-consumer-secret",
    resource_owner_key="your-token-id",
    resource_owner_secret="your-token-secret",
    realm=ACCOUNT_ID,
    signature_method="HMAC-SHA256"
)

response = requests.get(f"{BASE_URL}/customer/123", auth=auth)
print(response.status_code, response.json())

JavaScript/Node.js: OAuth 2.0 M2M token request

// Input:  clientId, certificateId, privateKey (PEM), accountId
// Output: access_token string

const jwt = require("jsonwebtoken"); // v9.x
const axios = require("axios");      // v1.x
const fs = require("fs");

const ACCOUNT_ID = "TSTDRV1234567";
const CLIENT_ID = "your-client-id";
const CERT_ID = "your-certificate-id";
const TOKEN_URL = `https://${ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token`;

const privateKey = fs.readFileSync("key.pem", "utf8");
const assertion = jwt.sign(
  { iss: CLIENT_ID, scope: "rest_webservices", aud: TOKEN_URL,
    exp: Math.floor(Date.now() / 1000) + 300,
    iat: Math.floor(Date.now() / 1000) },
  privateKey,
  { algorithm: "RS256", header: { kid: CERT_ID } }
);

const params = new URLSearchParams({
  grant_type: "client_credentials",
  client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  client_assertion: assertion,
});

const response = await axios.post(TOKEN_URL, params);
console.log("Token:", response.data.access_token);

cURL: Test OAuth 2.0 M2M token endpoint

# Input:  JWT assertion (pre-built), account ID
# Output: JSON with access_token, token_type, expires_in

curl -X POST \
  "https://TSTDRV1234567.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=YOUR_JWT_ASSERTION_HERE"

# Expected: { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

Data Mapping

Authentication Credential Mapping (TBA to OAuth 2.0 Migration)

Data Type Gotchas

• Account ID format: Use the account ID exactly as shown in Setup > Company > Company Information. Underscores for sandbox (e.g., TSTDRV1234567_SB1). Getting this wrong causes "invalid_grant". [src1]
• Realm parameter: TBA requires realm=ACCOUNT_ID in OAuth header. OAuth 2.0 encodes account in the URL instead. Remove realm logic when migrating. [src2]
• Token storage: TBA tokens can be stored permanently. OAuth 2.0 access tokens must be refreshed — integration needs token caching with TTL logic. [src5]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Certificate expiration (M2M): Certificates have a finite lifetime. When they expire, all API calls fail with invalid_grant. Fix: Monitor cert expiration; rotate at least 30 days before expiry. [src3]
• Sandbox refresh destroys M2M setup: M2M mapping cleared even though integration record is copied. Fix: Automate M2M recreation as part of sandbox refresh runbook. [src3]
• TBA signature clock skew: Timestamp in OAuth 1.0a header; >5 min drift causes failures. Fix: Use NTP; include clock sync in health monitoring. [src2]
• Token caching race condition: Multiple processes share expired OAuth 2.0 token; all request new tokens simultaneously. Fix: Single-writer refresh with distributed lock. [src5]
• Integration record deactivation: Admin deactivates record, breaking all connected systems. Fix: Monitor integration record status; alert on changes. [src6]

Anti-Patterns

Wrong: Hardcoding TBA tokens in source code

# BAD -- tokens in code, impossible to rotate without redeployment
auth = OAuth1(
    client_key="abc123",
    client_secret="secret456",
    resource_owner_key="tok789",
    resource_owner_secret="toksecret012",
    realm="TSTDRV1234567",
    signature_method="HMAC-SHA256"
)

Correct: Load credentials from environment / secrets manager

# GOOD -- credentials externalized, rotatable without code changes
import os
auth = OAuth1(
    client_key=os.environ["NS_CONSUMER_KEY"],
    client_secret=os.environ["NS_CONSUMER_SECRET"],
    resource_owner_key=os.environ["NS_TOKEN_ID"],
    resource_owner_secret=os.environ["NS_TOKEN_SECRET"],
    realm=os.environ["NS_ACCOUNT_ID"],
    signature_method="HMAC-SHA256"
)

Wrong: Building a new SOAP integration in 2026

# BAD -- SOAP sunset 2028.2. New SOAP blocked after 2027.1.
from zeep import Client
wsdl = f"https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/wsdl/v2025_2_0/netsuite.wsdl"
client = Client(wsdl)

Correct: Use REST Web Services with OAuth 2.0

# GOOD -- REST is the future. OAuth 2.0 is the preferred auth.
import requests
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(
    f"https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/record/v1/salesOrder",
    headers=headers,
    params={"q": "status IS SalesOrd:B"}
)

Wrong: Requesting a new M2M token for every API call

# BAD -- unnecessary token requests; wastes time and may hit rate limits
def make_api_call(endpoint):
    token = get_new_token()  # 200-500ms overhead EVERY call
    return requests.get(endpoint, headers={"Authorization": f"Bearer {token}"})

Correct: Cache the token and refresh on expiry

# GOOD -- cache token, refresh only when expired
import time
_token_cache = {"token": None, "expires_at": 0}

def get_token():
    if time.time() < _token_cache["expires_at"] - 60:  # 60s buffer
        return _token_cache["token"]
    resp = request_new_token()
    _token_cache["token"] = resp["access_token"]
    _token_cache["expires_at"] = time.time() + resp["expires_in"]
    return _token_cache["token"]

Common Pitfalls

• Assuming OAuth 2.0 works with SOAP: It does not. If your integration uses SOAP, OAuth 2.0 will fail. Verify your API surface before choosing auth. [src1, src4]
• Forgetting to recreate M2M setup in sandbox: Sandbox refresh clears M2M mappings. Integration tests break immediately. Fix: Include M2M setup in sandbox refresh checklist. [src3]
• Using RSA 2048-bit keys for M2M: NetSuite requires RSA 3072 or 4096 bit. 2048-bit keys are rejected. Fix: Always specify -newkey rsa:4096. [src3]
• Not planning for the 2027.1 cutoff: After 2027.1, cannot create new TBA integrations. Fix: Audit integration provisioning scripts; switch to OAuth 2.0 before 2027.1. [src2]
• Clock skew breaking TBA: NTP drift >5 min causes all TBA requests to fail. Fix: Ensure NTP is running; add clock sync monitoring. [src2, src6]
• Ignoring certificate rotation for M2M: Self-signed certs expire. Unlike TBA tokens (permanent), M2M certs have hard expiration. Fix: Set calendar alerts; use Certificate Rotation Endpoint. [src3]

Diagnostic Commands

# Test OAuth 2.0 M2M token request
curl -s -X POST \
  "https://ACCOUNT_ID.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token" \
  -d "grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=JWT_HERE" \
  | python3 -m json.tool

# Check certificate expiration date
openssl x509 -in cert.pem -noout -enddate

# Check certificate key length
openssl x509 -in cert.pem -noout -text | grep "Public-Key"

# Test REST API with bearer token
curl -s -X GET \
  "https://ACCOUNT_ID.suitetalk.api.netsuite.com/services/rest/record/v1/customer?limit=1" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  | python3 -m json.tool

# Check integration record status (via SuiteQL)
curl -s -X POST \
  "https://ACCOUNT_ID.suitetalk.api.netsuite.com/services/rest/query/v1/suiteql" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Prefer: transient" \
  -d '{"q": "SELECT id, name, isinactive FROM integration WHERE isinactive = '\''F'\'' ORDER BY id"}'

Version History & Compatibility

Deprecation Policy

Oracle NetSuite supports each SOAP endpoint for 3 years from release. After 3 years, the endpoint becomes "unsupported but available" and is eventually disabled. OAuth 2.0 is the long-term standard; TBA blocked for new integrations at 2027.1; SOAP fully disabled at 2028.2. [src4]

When to Use / When Not to Use

Important Caveats

• SOAP + OAuth 2.0 incompatibility is permanent: Oracle has no plans to add OAuth 2.0 support to SOAP. The strategy is to sunset SOAP entirely. If you need SOAP-only functionality, wrap it in a RESTlet. [src4]
• "TBA still works" does not mean "TBA is recommended": Existing TBA integrations continue past 2027.1, but migrate proactively. Security auditors increasingly flag permanent non-expiring tokens. [src2, src5]
• M2M certificate management is an operational burden: Unlike TBA (set and forget), OAuth 2.0 M2M requires certificate lifecycle management. Factor this into operational cost. [src3]
• Rate limits are auth-method-agnostic: Switching from TBA to OAuth 2.0 does not change your API rate limits. Limits are determined by account tier and API surface. [src1]
• This information is subject to change: Oracle may accelerate or adjust the deprecation timeline. Always verify against the latest NetSuite release notes and SOAP Removal Plans FAQ. [src4]