Authentication

SuitePortal supports two authentication methods for connecting to the NetSuite REST API:

Both methods use the same SuitePortal CLI and client API — the only difference is the credentials in your .env file.

Which Should I Use?

OAuth 2.0 M2M is NetSuite's recommended approach for server-to-server integrations going forward. It uses a certificate-based flow where:

• No user-specific access tokens are needed
• Identity is tied to a certificate mapping, not a token
• Credentials don't expire (only the certificate, which you control)

Token-Based Auth (TBA) is the established method and still fully supported. Use it if:

• Your NetSuite account already has TBA tokens configured
• You need the simplest possible setup
• Your organization hasn't adopted OAuth 2.0 M2M yet

Token-Based Authentication (TBA)

TBA uses OAuth 1.0a with HMAC-SHA256 signing. Every request is signed with your consumer and token credentials.

Setup

See the full NetSuite Setup guide for step-by-step instructions.

Environment Variables

NETSUITE_AUTH_TYPE=tba
NETSUITE_ACCOUNT_ID=1234567_SB1
NETSUITE_CONSUMER_KEY=your_consumer_key
NETSUITE_CONSUMER_SECRET=your_consumer_secret
NETSUITE_TOKEN_ID=your_token_id
NETSUITE_TOKEN_SECRET=your_token_secret

Programmatic Usage

import { createClient } from './.suiteportal/client';

const ns = await createClient({
  authType: 'tba',
  accountId: '1234567_SB1',
  consumerKey: '...',
  consumerSecret: '...',
  tokenId: '...',
  tokenSecret: '...',
});

OAuth 2.0 Machine-to-Machine (M2M)

OAuth 2.0 M2M uses the Client Credentials grant with a JWT assertion signed by your private key. SuitePortal automatically handles token exchange and refresh.

How It Works

1. You generate a public/private key pair
2. Upload the public certificate to NetSuite and map it to an entity + role
3. SuitePortal signs a JWT with your private key, exchanges it for a Bearer token
4. The Bearer token is used for API requests (auto-refreshed every 60 minutes)

Setup

See the full NetSuite Setup guide for step-by-step instructions.

Environment Variables

NETSUITE_AUTH_TYPE=oauth2
NETSUITE_ACCOUNT_ID=1234567_SB1
NETSUITE_CLIENT_ID=your_client_id
NETSUITE_CERTIFICATE_ID=your_certificate_id
NETSUITE_PRIVATE_KEY=-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----

Optional Variables

Programmatic Usage

import { createClient } from './.suiteportal/client';

const ns = await createClient({
  authType: 'oauth2',
  accountId: '1234567_SB1',
  clientId: '...',
  certificateId: '...',
  privateKey: fs.readFileSync('./private.pem', 'utf8'),
});

Supported Algorithms

Token Lifecycle

• Access tokens are valid for 60 minutes
• SuitePortal automatically refreshes tokens 5 minutes before expiry
• No refresh tokens — a new JWT assertion is created for each token request
• If a request returns 401, the token is cleared and re-fetched on the next request
• Concurrent requests during a token refresh share the same in-flight refresh (no thundering herd)

Switching Auth Methods

Switching between TBA and OAuth 2.0 only requires changing your .env file. No code changes are needed — the CLI and client detect the auth type automatically from NETSUITE_AUTH_TYPE.