NetSuite Token-Based Authentication Setup for Unified

February 12, 2026

Unified connects to NetSuite using Token-Based Authentication (TBA) (OAuth 1.0a style). You will provide 5 values:

1. Realm / Account ID
2. Consumer Key
3. Consumer Secret
4. Token ID (a.k.a. Token Key)
5. Token Secret

'Realm' in most client libraries/connectors refers to the NetSuite Account ID.

What you need before starting

• Admin access (recommended) OR a NetSuite admin to perform the enablement + token creation.
• The user you create the token for must have the correct role assigned, and the token must be generated against that role.

1) Enable the required NetSuite features

1.1 Enable Token-Based Authentication (TBA)

In NetSuite:

• Go to Setup → Company → Enable Features
• Open the SuiteCloud tab
• In Manage Authentication, enable:
  • ✅ Token-Based Authentication

(Depending on your NetSuite setup, you may also see toggles for OAuth; for Unified's TBA flow, the key requirement is Token-Based Authentication.)

1.2 Enable REST Web Services (if you're using SuiteTalk REST endpoints)

Ensure REST Web Services is enabled in Enable Features (commonly under SuiteCloud)

2) Find your 'Realm' / Account ID

Unified's 'Realm ID' is your NetSuite Account ID.

Option A (fast): from the URL

When logged into NetSuite, your account ID is visible in the URL. Oracle describes this approach.

Example:

• https://1234567.app.netsuite.com/... → Account ID = 1234567

Option B: from Company Information

• Setup → Company → Company Information
• Find Account ID

Sandbox note: your account ID may include a sandbox suffix like -SB1 (format varies by account).

3) Create the Integration Record (Consumer Key / Secret)

This is where you generate:

• Consumer Key
• Consumer Secret

Steps:

1. Go to Setup → Integration → Manage Integrations → New
2. Give it a name like 'Unified Integration'
3. Set State = Enabled
4. Go to the Authentication tab
5. ✅ Check Token-Based Authentication
6. Save

Oracle's help doc explicitly calls out checking Token-based Authentication on the Integration Record.

After saving, NetSuite will display the Consumer Key and Consumer Secret. Copy them somewhere safe (you may not be able to view the secret again).

✅ Provide these to Unified as:

• consumer_key
• consumer_secret

4) Create / Configure the Role used for the token

This is the most important part for avoiding 401 INVALID_LOGIN and permission issues.

Recommended: Use Administrator Role

The simplest and most reliable method:

• Use Administrator role
• Create the access token under Administrator

This ensures:

• All record access works
• All subsidiaries are accessible
• No hidden permission failures
• Faster setup

Optional: Create a Dedicated Unified API Role

If your security policy requires a restricted role, create a custom role and assign the following permissions.

Required Permissions (If Using Custom Role)

Below is the complete permission set required for full accounting integration support.

⚠ NOTE: This list may be adjusted depending on your Unified workflows.

Transaction Permissions

Reports Permissions

Lists Permissions

Setup Permissions

Important Notes

• The token inherits permissions from the role selected when creating the token.
• If you create the token under the wrong role, API calls will fail.
• Subsidiary access is controlled by role restrictions — ensure the role has access to all relevant subsidiaries.

5) Assign the Role to the User who will own the token

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

Steps:

1. Go to Lists → Employees → Employees
2. Select the user (or create an 'API User' like unified-api@yourcompany.com)
3. Open the Access tab
4. Ensure the Administrator role (recommended) OR Unified API Role (if custom) is assigned to this user
5. Save

6) Create the Access Token (Token ID / Token Secret)

This generates:

• Token ID (Token Key)
• Token Secret

Where to create it

Typically:

• Setup → Users/Roles → Access Tokens → New
  (or 'Manage Access Tokens' depending on your NetSuite UI)

You will select:

• Application / Integration Record = the integration you created ('Unified Integration')
• User = the user you assigned the role to
• Role = Administrator (recommended) OR Unified API Role
• Token name (optional but recommended)

Save → NetSuite displays Token ID and Token Secret. Copy them immediately.

✅ Provide these to Unified as:

• token_id
• token_secret

Important: the role you select when creating the token is the role whose permissions will be enforced on all API calls made with that token.

7) What to provide to Unified (the 5 inputs)

When connecting NetSuite in Unified, enter:

1. realm_id (NetSuite Account ID)
2. consumer_key
3. consumer_secret
4. token_id
5. token_secret

8) Validation & troubleshooting checklist

8.1 If you get 401 INVALID_LOGIN

This almost always means one of:

• Token created under the wrong role
• Token/user not permitted to use tokens (missing User Access Tokens / Access Token Management)
• Wrong realm/account id (especially sandbox vs prod)
• Wrong consumer key/secret paired with the token
• Integration record disabled

NetSuite's error message itself suggests checking the Login Audit Trail, which is the best source of truth:

• Setup → Users/Roles → User Management → View Login Audit Trail
  Look for token-based login details.

8.2 Sandbox vs Production

Make sure:

• Sandbox token is used only for sandbox
• Production token only for production
• Realm/account ID matches the environment