Token Based Authentication

When fetching or deploying using the theme and extension developer tools, users must authenticate with NetSuite. In previous releases, developer tool users were able to authenticate by providing their NetSuite user name and password. Now two-factor authentication (2FA) is mandatory on all NetSuite accounts using NetSuite 2018.2 and later. To support NetSuite 2FA, the developer command-line tools require token-based authentication for fetch and deploy operations. You can generate and manage tokens as described in the following topics:

Generate Tokens for Authentication

Before you can generate a token for authentication, you must:

  • Have the Token Based Authentication feature enabled in the NetSuite account if you are working on a production account. For more information, see Enable the Token-based Authentication Feature.

  • Have a NetSuite role that provides the permissions needed to fetch from and deploy to NetSuite. The Administrator role provide these permissions by default. For more information, see Developer Tool Roles and Permissions.

Note:

For release 2021.2.1 and later accounts that have account-specific domains, you must specify your account number with the gulp command to fetch or deploy. Keep this in mind when reviewing the following procedures. For more information about using the --account parameter with fetch and deploy commands, see Gulp Command Reference for Theme and Extension Developer Tools.

To generate an initial token for authentication:

Note:

After generating an initial authentication token, each subsequent fetch or deploy operation uses this token unless you specify the --to parameter as described in the following procedure.

  1. The first time you use a gulp command to fetch or deploy, the Commerce developer tools prompt for an authentication ID. You can enter any alphanumeric string for the authentication ID, which represents your NetSuite account and role.

  2. If you are already logged into NetSuite, you are prompted to select the NetSuite account and role that you want to use for the current fetch/deploy operation. If you are not logged into NetSuite, you are prompted to do so.

  3. In NetSuite, select the Allow button to generate the token and associated secret that is required for access.

  4. In NetSuite, when you see a message that the authentication process will continue in your CLI application, you can close the NetSuite window and the fetch/deploy operation continues and completes in the Commerce developer tool.

To generate a new token for authentication:

  1. You can generate a new token for authentication by specifying the --to parameter when you fetch or deploy. For example: gulp extension:deploy --to

  2. The developer tools give you the option to choose a saved token or to generate a new token.

    • The saved tokens you have previously used to authenticate are listed by authentication ID and account.

    • To generate a new token, choose the New token option.

  3. The Commerce developer tools prompt for an authentication ID. You can enter any alphanumeric string for the authentication ID, which represents your NetSuite account and role.

  4. If you are already logged into NetSuite, you are prompted to select the NetSuite account and role that you want to use for the current fetch/deploy operation. If you are not logged into NetSuite, you are prompted to do so.

  5. In NetSuite, select the Allow button to generate the token and associated secret that is required for access.

  6. In NetSuite, when you see a message that the authentication process will continue in your CLI application, you can close the NetSuite window and the fetch/deploy operation continues and completes in the Commerce developer tool.

Manage Authentication Tokens

If you need to view, edit, or revoke previously generated tokens, you can do so in NetSuite. To learn more, see Manage TBA Tokens in the NetSuite UI.

Tokens that you use to connect to NetSuite from the developer tools are saved in a local file called .nstba. On Windows, the .nstba file is stored in the C:\Users\user_name directory. You can edit the .nstba file to manage the saved tokens that are listed in the developer tools when you specify the --to parameter for a fetch or deploy operation.

Related Topics

Commerce Developer Tools Reference
Mixed Domains in a Local Server
Secure HTTP (HTTPS) with the Local Server
Troubleshooting the Developer Tools

General Notices