Secure Credentials Storage for SuiteCloud SDK

Starting in 2025.1, SuiteCloud SDK uses Public-Key Cryptography Standards #12 (PKCS#12) to generate a password-protected credentials file.

When you authenticate for the first time using SuiteCloud SDK tools, the PKCS#12 credentials file is created and stored on your local machine in the .suitecloud-sdk folder in your home directory. This file contains encrypted authentication data, so you don't have to authenticate again in future sessions. The credentials file name depends on the authentication option you used: credentials_browser_based.p12 for browser-based authentication or credentials_ci.p12 for machine-to-machine authentication.

Important:

Browser-based authentication and Machine-to-machine authentication use different credential files to store authentication data. You can set up your environment to use only one authentication option at a time.

SuiteCloud SDK checks for specific environment variables and the availability of secure storage to determine if you've got the right setup for the authentication option that you're trying to run. For more information, see Execution Context for Secure Credentials Storage.

To keep your credentials file safe, SuiteCloud SDK encrypts it with a password or passkey:

For browser-based authentication, SuiteCloud SDK auto-generates the passkey and updates it regularly. This passkey is stored in your machine's secure storage service (like Credential Manager for Windows, Keyring for Linux, or Keychain for macOS).
For machine-to-machine authentication or browser-based authentication in fallback mode, you must manually define the passkey using an environment variable and update it regularly.

If you delete the credentials file, any authentication IDs you set up before will be lost. A new credentials file will be created when you set up your account again.

Read the following topics for more information:

Watch the following help video for information about Secure Credentials Storage for SuiteCloud SDK:

Browser-Based Authentication Standard Process and Fallback Mode

When you use browser-based authentication, SuiteCloud SDK creates the credentials file (credentials_browser_based.p12) and encrypts it with an auto-generated passkey. The passkey is stored in your machine's secure storage and is updated regularly when the token expires.

When you do operations that require NetSuite authentication, SuiteCloud SDK retrieves the passkey from secure storage and uses it to decrypt the credentials file. For this reason, ensure that secure storage is accessible and properly configured on your machine if you want to use browser-based authentication.

If secure storage isn't available, you can define a fallback passkey by creating the SUITECLOUD_FALLBACK_PASSKEY environment variable. This passkey must contain 32 to 100 alphanumeric characters. For information about how to set environment variables for different operating systems, see Setting Up Environment Variables for SuiteCloud SDK Tools.

Important:

The fallback passkey is a temporary solution for when secure storage isn't available, is locked, or isn't properly configured. If you can't use secure storage, you can keep using the fallback passkey for browser-based authentication.

In this case, changing the passkey is your responsibility, and it should be done regularly for optimal security. Note that when you change the passkey, the current credentials file will no longer work. After changing the passkey, you must delete the old credentials file and set up your account again.

When secure storage is available in your machine, ensure to remove the fallback passkey environment variable. Otherwise, you'll get an error.

Machine-to-Machine Authentication (CI/CD)

Machine-to-machine authentication uses two environment variables:

SUITECLOUD_CI: Set this to 1 (preferred) or anything other than zero to run operations in a CI/CD environment using machine-to-machine authentication.
SUITECLOUD_CI_PASSKEY: Set the passkey you'll use to create the credentials file. The passkey needs 32 to 100 alphanumeric characters and should be updated regularly.

Important:
When you change the passkey, your current credentials file won't work anymore. After changing it, you'll need to delete the old credentials file and set up your account again.

To set up and manage authentication IDs for machine-to-machine authentication, you only need to set the SUITECLOUD_CI_PASSKEY environment variable. To use the authentication IDs to run operations that need authentication, you need to set both the SUITECLOUD_CI_PASSKEY and SUITECLOUD_CI environment variables.

When you use machine-to-machine authentication, SuiteCloud SDK creates the credentials file (credentials_ci.p12) and encrypts it with the passkey you set in the SUITECLOUD_CI_PASSKEY environment variable. When you do operations that require NetSuite authentication, SuiteCloud SDK retrieves the passkey from the environment variable and uses it to decrypt the credentials file.

To use your authentication credentials in your CI/CD environment, here's what you need to do:

Upload the credentials_ci.p12 file to your CI/CD environment securely.
Set the SUITECLOUD_CI_PASSKEY environment variable in your CI/CD environment and use the same passkey you used to create the credentials file.
Set the SUITECLOUD_CI environment variable to 1 in your CI/CD environment to enable machine-to-machine authentication.

With the credentials and environment variables set, SuiteCloud SDK tools can do operations that need NetSuite authentication in the CI/CD pipeline.

For more information, see Using Machine-to-Machine Authentication for CI/CD Environments.

For information about setting environment variables for different operating systems, see Setting Up Environment Variables for SuiteCloud SDK Tools.

General Notices