---
title: "NetSuite Authentication Setup for Unified"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/netsuite_authentication_setup_for_unified-icon.svg
date: 2026-02-12T19:38:00.000Z
updated: 2026-09-04T14:27:43.968Z
tag: Guides
description: "Unified supports two authentication methods for connecting to NetSuite,"
url: "https://unified.to/blog/netsuite_authentication_setup_for_unified"
---

# NetSuite Authentication Setup for Unified
------
_February 12, 2026_

Unified supports **two** authentication methods for connecting to NetSuite:

1. **[OAuth](/embeddedauth) 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?**


|                             | OAuth 2.0                                                                               | Token-Based Authentication (TBA)                                    |
| --------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Setup effort                | Medium — create your OAuth Integration Record once, then customers sign in              | Higher — create Integration Record + Access Token                   |
| Credentials Unified stores  | Workspace Client ID/Secret + per-connection access_token/refresh_token (auto-refreshed) | 5 long-lived secrets                                                |
| Best for                    | Most customers; new / multitenant SaaS (use Public Client / partner app)                | Existing TBA setups; quick per-account connect until OAuth is ready |
| Token lifespan              | Access token refreshes automatically                                                    | Tokens are long-lived; rotate manually                              |
| What you provide to Unified | Workspace: Client ID/Secret. Connection: Account ID + browser login                     | Realm + Consumer Key/Secret + Token ID/Secret                       |
If you're not sure, **start with OAuth 2.0**. **Important:** Unified does **not** currently provide a pre-registered NetSuite OAuth 2.0 application. You must create your own NetSuite Integration Record (or use TBA).


---


## **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](/technology)" 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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771733782.html) and [OAuth 2.0 Authorization Code Grant Flow](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_158074210415.html).
- 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:


| Unified field              | NetSuite value |
| -------------------------- | -------------- |
| realm_id (or "Account ID") | from Step 2    |
| consumer_key               | from Step 4B.1 |
| consumer_secret            | from Step 4B.1 |
| token_id                   | from Step 4B.3 |
| token_secret               | from Step 4B.3 |
---


## **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**


| Permission               | Level |
| ------------------------ | ----- |
| Access Payment Audit Log | Full  |
| Bill Purchase Orders     | Full  |
| Bills                    | Full  |
| Cash Sale                | Full  |
| Cash Sale Refund         | Full  |
| Credit Memo              | Full  |
| Cross Charge Journal     | View  |
| Customer Deposit         | Full  |
| Customer Payment         | Full  |
| Customer Refund          | Full  |
| Enter Vendor Credits     | Full  |
| Find Transaction         | Full  |
| Intercompany Adjustments | Full  |
| Invoice                  | Full  |
| Invoice Approval         | Full  |
| Invoice Sales Orders     | Full  |
| Item Receipt             | Full  |
| Item Shipment            | Full  |
| Journal Approval         | Full  |
| Make Journal Entry       | Full  |
| Opportunity              | Full  |
| Paycheck Journal         | Full  |
| Receive Order            | Full  |
| System Journal           | Full  |
**Reports**


| Permission         | Level |
| ------------------ | ----- |
| Transaction Detail | View  |
**Lists**


| Permission                      | Level |
| ------------------------------- | ----- |
| Accounts                        | Full  |
| Address List in Search          | Full  |
| Contact-Subsidiary Relationship | View  |
| Contacts                        | Full  |
| Currency                        | Full  |
| Customers                       | Full  |
| Employee Record                 | Full  |
| Employees                       | Full  |
| Inventory Cost Template         | View  |
| Locations                       | Full  |
| Partners                        | Full  |
| Perform Search                  | View  |
| Subsidiaries                    | Full  |
| Vendors                         | Full  |
**Setup**


| Permission                                   | Level                   |
| -------------------------------------------- | ----------------------- |
| Access Token Management                      | Full _(TBA only)_       |
| Integration Application                      | Full                    |
| Log in using Access Tokens                   | Full _(TBA only)_       |
| Log in using OAuth 2.0 Access Tokens         | Full _(OAuth 2.0 only)_ |
| OAuth 2.0 Authorized Applications Management | Full _(OAuth 2.0 only)_ |
| REST Web Services                            | Full                    |
| Two-Factor Authentication Base               | Full                    |
| User Access Tokens                           | Full _(TBA only)_       |
**Notes:**

- 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.