Using NetSuite’s Token Based Authentication with SuiteTalk

NetSuite’s OAuth is very different from the standard oauth flow: setting up a user for token based auth is very cumbersome. It requires digging around in the NetSuite GUI, creating roles, and copy/pasting various keys.

Why use token based authentication? The alternative is email + password based authentication. This method works fine, but passwords expire every six months; resetting passwords every six months is a huge pain for a SAAS product that integrates with NetSuite. Plus, email + password auth is much less secure (an attacker can login to the GUI with a email and password).

Here’s a guide to getting setup with token based authentication. Note that you must be using a SuiteTalk API versions greater than 2015_2.

1. Create a Integration Record

The integration record identifies the application in NetSuite’s system.

  1. Visit the integrations page or global search for page:integrations
  2. Create a integration record if none exists. After you create the record you will need to copy/paste the consumer key and consumer secret to your secrets file.
    • Name: Your-Application-Name
    • Authentication: Token-Based Authentication
    • State: Enabled
  3. If the integration record already exists, but you don’t have the consumer key and consumer secret, edit the record, then press “Reset Credentials”.

2. Enable Token Based Authentication

  1. Setup > Company > Setup Tasks > Enable Features > SuiteCloud > Manage Authentication
  2. Make sure “Token Based Authentication” is enabled
  3. Save

If this feature is not enabled, you will not see the permissions required in the next step.

3. Create a Token Role

Strangely enough, the administrator does not have token permissions by default. If you do not create a token role and assign it to your administrator, you will get a “Login access has been disabled for this role.” error when creating a token.

  1. Global search for page:role, then choose “New Role”
  2. Navigate to “Permissions > Setup” and add the following permissions:
    • User Access Token: Full
    • Access Token Management: Full
    • Web Services: Full

4. Add Token Management Permissions

  1. Global search for page:employees
  2. Edit your employee record
  3. Navigate to “Access > Roles” and add the token auth role you just created

5. Create Access Tokens

  1. Global search for page: tokens
  2. New Access Token
  3. Select the application and role we created earlier, then press save.
  4. Copy/past the token ID and token secret to your secrets file.s

6. Configure Your Client

Here’s how to setup the netsuite ruby client with token based authentication:

NetSuite.configure do
  reset!

  account          ENV['NETSUITE_ACCOUNT']
  consumer_key     ENV['NETSUITE_CONSUMER_KEY']
  consumer_secret  ENV['NETSUITE_CONSUMER_SECRET']
  token_id         ENV['NETSUITE_TOKEN_ID']
  token_secret     ENV['NETSUITE_TOKEN_SECRET']
end
  • Derek Adams

    Hi Michael,
    Have you ever run into issues with Netsuite caching permissions on the token login role? I’m trying to push some data and I’m getting nothing but “Permission Violation: You need the ‘Lists -> Contacts’ permission to access this page.” I added that permission hours ago, but nothing seems to work. If I switch to regular credentials I can push fine.