NetSuite Authentication Setup for Unified

February 12, 2026

Unified supports two authentication methods for connecting to NetSuite:

1. OAuth 2.0 (Authorization Code Grant) — browser-based login. Recommended for most customers and for new integrations. You create a NetSuite Integration Record (Client ID / Client Secret), add those credentials to your Unified workspace, then each connection enters a NetSuite Account ID and completes browser consent. Tokens refresh automatically.
2. Token-Based Authentication (TBA / OAuth 1.0a) — you generate and paste 5 long-lived credentials per NetSuite account. Still supported today, but Oracle will not allow new TBA integrations starting with NetSuite 2027.1 (TBA end of support is tentatively planned later). Prefer OAuth 2.0 for new work.

Both methods talk to the same SuiteTalk REST Web Services API, so the underlying NetSuite feature flags and the role permissions list below are nearly identical. The main difference is how Unified obtains the access token.

"Realm" = NetSuite Account ID in every NetSuite client library and connector. We use the terms interchangeably below.

Which method should I choose?

What you need before starting (both methods)

• Admin access in NetSuite (recommended), OR a NetSuite admin available to enable features and grant role permissions.
• The role used for the connection must have the correct permissions (see Required Role Permissions below).
• For sandbox testing, know whether you are in Sandbox vs Production — your Account ID and credentials are different between environments.

Step 1 — Enable the required NetSuite features (both methods)

In NetSuite: Setup → Company → Enable Features → SuiteCloud tab.

Under Manage Authentication, enable:

• ✅ OAuth 2.0 (required for OAuth 2.0 method)
• ✅ Token-Based Authentication (required for TBA method)

Under SuiteTalk (Web Services), enable:

• ✅ REST Web Services

Without REST Web Services, all API calls return 401 regardless of which auth method you use, so make sure this is on.

Click Save.

Step 2 — Find your Realm / Account ID (both methods)

Your Realm is your NetSuite Account ID.

Option A — from the URL (fastest):

When logged into NetSuite, the Account ID is in the host portion of the URL.

Option B — from Company Information:

Setup → Company → Company Information → look for Account ID.

Sandbox note: Sandbox accounts include a suffix like _SB1 (or -SB1 in URLs). Use underscores when entering the Account ID into Unified (e.g. 1234567_SB1). Unified normalizes between the URL form (-sb1) and the OAuth realm form (_SB1) automatically.

Step 3 — Configure the Role used for the connection (both methods)

This is the most important step for avoiding 401 INVALID_LOGIN and "permission denied" errors. The role you use determines what Unified can read and write — for both OAuth 2.0 and TBA.

Recommended: use the Administrator role

The simplest and most reliable option:

• Use the Administrator role for the connecting user (OAuth 2.0), or for the token (TBA).

This guarantees:

• All record types are accessible
• All subsidiaries are accessible
• No hidden permission failures
• Fastest setup

Optional: create a dedicated "Unified API" custom role

If your security policy requires a least-privilege role, create one and grant the permissions in Required Role Permissions.

User-level restrictions can override role-level permissions. If you use a custom role, make sure the user account itself also has these permissions where applicable.

Step 4A — Connect using OAuth 2.0 (recommended)

OAuth 2.0 requires your own NetSuite Integration Record with Authorization Code Grant enabled. Unified does not ship a pre-registered NetSuite OAuth app. Store the Client ID and Client Secret on your NetSuite workspace integration in Unified, set the auth method to OAuth 2.0, then connect each customer account with their NetSuite Account ID + browser consent.

4A.1 Create a NetSuite Integration Record (OAuth 2.0)

In NetSuite:

• Go to Setup → Integration → Manage Integrations → New.
• Name it after your product (customers see this on the consent screen). Set State = Enabled.

On the Authentication tab: enable Authorization Code Grant; enable REST Web Services; set Redirect URI to Unified's callback for your data center (US: https://api.unified.to/oauth/code, EU: https://api-eu.unified.to/oauth/code, AU: https://api-au.unified.to/oauth/code). For multitenant SaaS (many customer NetSuite accounts authorizing one Client ID), enable Public Client (PKCE). Unified's NetSuite OAuth flow uses PKCE. Save and copy the Client ID and Client Secret immediately.

4A.2 Add OAuth credentials in Unified (workspace)

1. In the Unified dashboard, activate or edit the NetSuite workspace integration.
2. Choose authentication method OAuth 2.0 (not Token / TBA).
3. Paste your NetSuite Client ID and Client Secret, then save.
4. Until Client ID/Secret are saved and OAuth 2.0 is selected, the connect UI defaults to the TBA (five-field) form — which is why OAuth can look missing in the product UI.
5. Then connect a NetSuite account: start a NetSuite connection and enter the customer's NetSuite Account ID (e.g. 1234567 or 1234567_SB1).
6. Complete the NetSuite browser login / consent screen. Choose the Role to authorize under — Administrator or your custom least-privilege role with the permissions below.
7. Click Allow. Unified stores the access and refresh tokens for that connection. Each Unified connection is one NetSuite account (one Account ID).

The access token is refreshed automatically on expiry. A private Integration Record only works in the NetSuite account that created it. For multitenant SaaS you need a Public Client / partner-distributed NetSuite application (or each customer must install/trust your Integration Record).

4A.3 Make sure the authorizing user has the right role

The user who completes consent in NetSuite must have a role that:

1. Includes the permissions in Required Role Permissions below (including Log in using OAuth 2.0 Access Tokens).
2. Has access to all subsidiaries you want Unified to sync.
3. Confirm role assignment under Lists → Employees → Employees → user → Access tab.
4. Oracle references: Create Integration Records for OAuth 2.0 and OAuth 2.0 Authorization Code Grant Flow.

• You add Client ID/Secret yourself on the Unified workspace integration — you do not need to send them to Unified support.
• Consent branding shows your Integration Record name, not 'Unified', when using your own app.
• If OAuth is not configured on the workspace, Unified falls back to the TBA credential form.

1. After connecting, verify a simple read (for example list invoices or accounts) to confirm the consented role has the needed permissions.
2. To re-authorize later: revoke under Setup → Users/Roles → OAuth 2.0 Authorized Applications if needed, then reconnect in Unified.

Reference: NetSuite OAuth 2.0 Authorization Code Grant Flow (Oracle Help Center).

Step 4B — Connect using Token-Based Authentication (TBA)

If you chose TBA, you will provide Unified 5 values. TBA is still the simpler per-customer path today, but prefer OAuth 2.0 for new multitenant work (Oracle: no new TBA integrations from 2027.1).

• realm (NetSuite Account ID)
• consumer_key
• consumer_secret
• token_id (a.k.a. Token Key)
• token_secret

4B.1 Create the Integration Record (Consumer Key / Secret)

1. Setup → Integration → Manage Integrations → New
2. Name: e.g. "Unified Integration"
3. State: Enabled
4. On the Authentication tab:

• ✅ Token-Based Authentication
• (Leave OAuth 2.0 off unless you also plan to use OAuth 2.0 with the same record.)

1. Save — NetSuite displays the Consumer Key and Consumer Secret. Copy them immediately; the Consumer Secret cannot be viewed again.

These are the consumer_key and consumer_secret you'll give Unified.

4B.2 Assign the role to the user who will own the token

Tokens are created for a User + Role + Integration Record combination.

1. Lists → Employees → Employees
2. Select the user (or create a dedicated "API User" like unified-api@yourcompany.com)
3. Open the Access tab
4. Assign Administrator (recommended) OR your custom Unified API role
5. Save

4B.3 Create the Access Token (Token ID / Token Secret)

1. Setup → Users/Roles → Access Tokens → New (may be labelled "Manage Access Tokens" in some UIs)
2. Fill in:

• Application Name: the Integration Record you created (e.g. "Unified Integration")
• User: the user from 4B.2
• Role: Administrator (recommended) OR your Unified API role
• Token Name: optional but recommended (e.g. "Unified Production Token")

1. Save — NetSuite displays the Token ID and Token Secret. Copy them immediately.

The role you select here is the role whose permissions are enforced on every API call made with this token. Choosing the wrong role is the #1 cause of 401 INVALID_LOGIN and permission errors.

4B.4 Provide the 5 values to Unified

In the Unified connection form, enter:

Required Role Permissions

These apply to both OAuth 2.0 and TBA when you choose a custom (non-Administrator) role. The list is the full set required for full accounting + CRM + commerce + HRIS support. You can trim it based on which Unified object types you actually use.

User-level restrictions can override role-level permissions. Make sure the user has these permissions in addition to the role.

Transactions

• For TBA, the token inherits the permissions of the role selected when the token is created — not the user's default role.
• For OAuth 2.0, the access token inherits the permissions of the role selected during the NetSuite consent screen.
• Subsidiary access is controlled by role restrictions. If you use OneWorld, ensure the role has access to every subsidiary Unified must sync.

Validation & Troubleshooting

401 INVALID_LOGIN

This almost always means one of:

• Wrong role selected when the OAuth 2.0 consent was approved, or when the TBA token was created.
• Missing permissions on the role:
• OAuth 2.0: missing Log in using OAuth 2.0 Access Tokens and/or OAuth 2.0 Authorized Applications Management
• TBA: missing Log in using Access Tokens, Access Token Management, or User Access Tokens
• Wrong Account ID (especially mixing sandbox with production).
• REST Web Services not enabled at the account level.
• Integration Record disabled, or (OAuth) workspace missing Client ID/Secret / auth method still set to Token.
• Consumer key/secret paired with a token from a different Integration Record (TBA only).

The fastest way to diagnose is the Login Audit Trail:

Setup → Users/Roles → User Management → View Login Audit Trail

Filter by Token-based or OAuth 2.0 logins and look at the failure reason on the most recent attempt.

400 Bad Request / INSUFFICIENT_PERMISSION

The connection authenticated but the role lacks permission for the specific record type Unified is trying to access. Add the missing permission from the Required Role Permissions table (most commonly Lists → Subsidiaries, Lists → Accounts, or a Transaction permission).

Sandbox vs Production

• Sandbox tokens / OAuth 2.0 consents only work against the sandbox account.
• Sandbox URLs use -sb1 (e.g. 1234567-sb1.app.netsuite.com); the realm sent on API calls uses _SB1 (e.g. 1234567_SB1). Unified handles the conversion automatically — just enter the Account ID with the _SB1 underscore form when prompted.

Token rotation (TBA)

NetSuite TBA tokens don't expire by default, but your security policy may require rotation:

1. Create a new Access Token under the same User + Role + Integration Record.
2. Update the token_id and token_secret in Unified.
3. Revoke the old token in Setup → Users/Roles → Access Tokens.

Re-authorizing OAuth 2.0

If a user is removed or their role changes, the OAuth 2.0 grant may become invalid. To re-authorize:

1. In NetSuite: Setup → Users/Roles → OAuth 2.0 Authorized Applications → revoke the existing grant for your Integration Record (optional but recommended).
2. In Unified, reconnect the NetSuite integration. You'll be sent back through the NetSuite consent screen.