Token-Based Authentication (TBA) in NetSuite: Setup Guide

Token-Based Authentication (TBA) is the most widely used authentication method for NetSuite integrations. It uses OAuth 1.0a to generate a signed request header, giving you secure access to RESTlets and the REST Record API without exposing passwords.

What Is TBA?

TBA uses four credentials to authenticate API requests:

• Consumer Key — identifies your integration application
• Consumer Secret — secret for signing, paired with Consumer Key
• Token Key — identifies the specific user/access token
• Token Secret — secret paired with the Token Key

These four values are combined with a timestamp and nonce to produce an HMAC-SHA256 signature in the Authorization header.

Step 1: Enable Token-Based Authentication in NetSuite

1. Go to Setup > Company > Enable Features.
2. Click the SuiteCloud tab.
3. Under SuiteScript, check Client SuiteScript and Server SuiteScript.
4. Under Manage Authentication, check Token-Based Authentication.
5. Click Save.

Step 2: Create an Integration Record

1. Go to Setup > Integration > Manage Integrations > New.
2. Enter a Name for your integration (e.g., “My External App”).
3. Under Authentication, check Token-Based Authentication.
4. Uncheck Authorization Code Grant and Client Credentials if you only want TBA.
5. Click Save.
6. On the confirmation page, copy and securely store:
   — Consumer Key
   — Consumer Secret
   These are shown only once. Store them securely.

Step 3: Create an Access Token

1. Go to Setup > Users/Roles > Access Tokens > New.
2. Select the Application Name (your integration from Step 2).
3. Select the User who will authenticate (usually a dedicated API user).
4. Select the Role for this token (must have RESTlet/REST API permissions).
5. Enter a Token Name (e.g., “API Access Token”).
6. Click Save.
7. Copy and securely store:
   — Token Key
   — Token Secret
   These are also shown only once.

Step 4: Assign Permissions to the Role

The role assigned to the access token needs the correct permissions:

1. Go to Setup > Users/Roles > Manage Roles and find/edit your role.
2. Under Permissions > Setup, ensure these are included:
   — Log in using Access Tokens
   — REST Web Services (if using REST Record API)
   — SuiteScript (if using RESTlets)
3. Under Permissions > Transactions / Lists / Reports, add permissions for the record types your integration will access.
4. Click Save.

Step 5: Build the OAuth 1.0a Authorization Header

Every API request must include an Authorization header. Here’s the structure:

Authorization: OAuth
  realm="[ACCOUNT_ID]",
  oauth_consumer_key="[CONSUMER_KEY]",
  oauth_token="[TOKEN_KEY]",
  oauth_signature_method="HMAC-SHA256",
  oauth_timestamp="[UNIX_TIMESTAMP]",
  oauth_nonce="[RANDOM_STRING]",
  oauth_version="1.0",
  oauth_signature="[COMPUTED_SIGNATURE]"

Computing the Signature (Python Example)

import hmac
import hashlib
import base64
import time
import random
import string
import urllib.parse

def generate_nonce(length=16):
    return ''.join(random.choices(string.ascii_letters + string.digits, k=length))

def build_oauth_header(method, url, account_id, consumer_key, consumer_secret, token_key, token_secret, params=None):
    timestamp = str(int(time.time()))
    nonce = generate_nonce()
    
    oauth_params = {
        'oauth_consumer_key': consumer_key,
        'oauth_token': token_key,
        'oauth_signature_method': 'HMAC-SHA256',
        'oauth_timestamp': timestamp,
        'oauth_nonce': nonce,
        'oauth_version': '1.0'
    }
    
    all_params = {**oauth_params, **(params or {})}
    sorted_params = '&'.join(f'{urllib.parse.quote(k, safe="")}={urllib.parse.quote(str(v), safe="")}' 
                             for k, v in sorted(all_params.items()))
    
    base_string = f'{method.upper()}&{urllib.parse.quote(url, safe="")}&{urllib.parse.quote(sorted_params, safe="")}'
    signing_key = f'{urllib.parse.quote(consumer_secret, safe="")}&{urllib.parse.quote(token_secret, safe="")}'
    
    signature = base64.b64encode(
        hmac.new(signing_key.encode(), base_string.encode(), hashlib.sha256).digest()
    ).decode()
    
    oauth_params['oauth_signature'] = signature
    header_parts = ', '.join(f'{k}="{urllib.parse.quote(str(v), safe="")}"' for k, v in oauth_params.items())
    
    return f'OAuth realm="{account_id}", {header_parts}'

Step 6: Test Your TBA Setup

Use Postman with OAuth 1.0 type and your four credentials to test a simple GET request to the REST Record API:

GET https://[account-id].suitetalk.api.netsuite.com/services/rest/record/v1/customer/1

A successful response returns the customer record. A 401 means your credentials or signature are incorrect.

TBA Security Best Practices

• Never store credentials in code — use environment variables or a secrets manager.
• Create a dedicated API user with a restricted role (least-privilege principle).
• Generate one access token per integration/application, not per request.
• Rotate tokens periodically or when team members with access leave.
• Monitor token usage via Setup > Users/Roles > Access Tokens.

Next Steps

For a more modern authentication approach, explore OAuth 2.0 in NetSuite — which uses bearer tokens and is simpler to implement with standard OAuth 2.0 libraries.