Managing SuiteApp API Secrets

November 29, 2023 | 7 minute read
Radek Felkl
SDN Solutions Engineer EMEA
Text Size 100%:


Hello NetSuite Developers,

Welcome to our new blog series where we explore the ins and outs of secure coding practices within NetSuite. Today, we’re focusing on a critical aspect of modern development: safeguarding API credentials, tokens and keys.

NetSuite's API Secrets functionality is intended to conceal sensitive credentials to reduce the risk of illegal access and simplify the maintenance of application code. Your sensitive data should never be directly embedded within your codebase. Hardcoding credentials is akin to leaving your keys in the door – convenient, perhaps, but a security nightmare waiting to happen.

As of NetSuite 2021.2, the use of the nlapiEncrypt API to check the values of password fields was prohibited. NetSuite 2021.1 introduced new API methods that customers should use instead to verify password field values. Reading password field values can no longer be performed using any API method.

API Secrets are secure containers in your NetSuite environment where you can store sensitive information, such as tokens or passwords, to prevent exposure in your source code. To access the API Secrets page in your NetSuite account, navigate to Setup > Company > Preferences > API Secrets.

When creating a new secret, you must provide a name and a unique script ID. This ID should be clear and descriptive, as it serves as the handle you will use within your scripts. NetSuite prefixes the script ID of API Secret records with ‘custsecret’.

Note: Use your Dev/Publisher NetSuite account to manage your app's API Secrets.



















For the content of your secret, you have the option to type it in or upload a file. This feature is particularly useful for securely handling lengthy keys. You can manage access to your API secret in the Restrictions tab. It is recommended to restrict your application's API secret access.



















Once you have created your API Secret, you can reference it directly in your scripts. For instance, if you need to make a call to an external service that your app requires access to provide added value to your customers, you should use the secret's script ID to dynamically insert the token into your SFTP request headers instead of hard coding it.

API Secrets must be placed in your SuiteApp’s SDF Project Objects folder and referenced in your code using their script ID. Refer to example below.


<secret scriptid="custsecret_mytestingtoken">


define(['N/https', 'N/log'], (https, log) => {
    const execute = (context) => {

    const callGitHubAPI = () => {
        const requestOptions = {
            url: '',
            headers: {
                'Authorization': 'token {custsecret_mytestingtoken}',
                'User-Agent': 'NetSuite-SuiteScript',
                'Accept': 'application/vnd.github+json',
            credentials: ['custsecret_mytestingtoken']

        try {
            const response = https.get(requestOptions);
            const repositories = JSON.parse(response.body);
            log.debug('GitHub Repositories', JSON.stringify(repositories));
        } catch (error) {
            log.error('Error calling GitHub API', error);

    return { execute };

In this script, "custsecret_mytestingtoken " is a placeholder for the actual secret value stored securely within NetSuite. This ensures your credentials remain encrypted and invisible to anyone browsing through your code.

A few considerations to keep in mind:

•    When deploying a SuiteApp, ensure the API Secret is not created in the same account in the UI to avoid duplication errors (the API Secret must be created in a different account than the one you deploy on).
•    If your use case does not require SFTP or HTTPS, add an invalid domain restriction to ensure the decrypted secret remains safe from unsecure external services.

In conclusion, NetSuite’s API Secrets offer a secure and easy to use method to protect the confidentiality of your credentials. Adopting this best practice enhances your customer's account security and complies with the principle of least privilege, which is fundamental to secure software development.

NetSuite API Secrets Use Cases

In addition to securely storing sensitive data, API Secrets in NetSuite can be used in more advanced scenarios, particularly in generating OAuth signatures. By utilizing the N/crypto module, along with N/encode, developers can avoid the need for external JavaScript libraries, such as CryptoJS.js, for signature generation. This capability is not just about convenience; it significantly enhances security. Unlike custom record instances, where values might be more susceptible to unauthorized changes, API Secrets are far less vulnerable. The increased security stems from the stringent access restrictions that NetSuite enables for API Secrets. These can be tightly controlled, making them more secure against potential intrusions.

Furthermore, distributing API secrets via apps adds another layer of security. This is crucial in multi-tenant environments or when sharing your SuiteApps with other users, as it allows for the safe sharing of these secrets without exposing them to unnecessary risks, which is a key advantage.

The N/crypto module allows you to generate random numbers. This functionality is particularly useful in scenarios where you need to generate a secure OAuth nonce or non-repetitive, unpredictable value for encryption, token generation, or similar purposes.

Storing Customer Credentials for External System Connections in NetSuite

A common challenge encountered in integrated or hybrid SuiteApp development is securely storing customer credentials needed for connecting to external systems. NetSuite’s robust architecture allows for the secure storage of these credentials, ensuring that sensitive data is handled with the utmost care. When it comes to storing customer credentials for external system connections, a more convenient approach is to provide a custom form or suitelet to your customers, which leverages custom records in NetSuite. These records can securely hold credentials in encrypted fields, ensuring that they are not exposed or accessible to unauthorized users. This method is secure and offers flexibility, allowing you to structure data storage according to your application's specific needs and your customers' requirements.

Please remember that securely storing credentials is crucial, but it is equally important to ensure that they are accessible only to authorized users. Implementing role-based access controls and audit trails can help maintain the integrity and confidentiality of sensitive information.

Collecting Credentials Through a Custom Form with Enhanced Security

Using form.addCredentialField(options) in conjunction with https.createSecretKey(options) offers a robust solution for enhancing data security. The form.addCredentialField method enables the addition of a sensitive data input field in a Suitelet or custom form, ideal for entering API keys or passwords. This method ensures that user input is treated confidentially and securely handled by NetSuite's backend.

Conversely, https.createSecretKey(options) is instrumental in generating a secure, random encryption key. When these two methods are combined, they create a highly secure system where user-input credentials in a Suitelet or custom form are encrypted with a NetSuite-generated secret key. This encryption is crucial for the secure storage and safe transmission of user credentials.

To complement the encryption process, NetSuite also provides https.createSecureString(options). This function is used for decrypting the data that was encrypted using the secret key. It plays a vital role in securely handling the credentials when they need to be retrieved and used, ensuring that the data remains protected throughout its lifecycle in your application.

For example, credentials entered by a user in a form field created with Form.addCredentialField can be encrypted server-side using a key generated by https.createSecretKey. This encrypted data is then securely stored within NetSuite, for instance, in a custom record or another secure storage mechanism. When the need arises to use these credentials, https.createSecureString can be employed to decrypt them safely, maintaining the integrity and confidentiality of the sensitive data.

Incorporating these functionalities into your NetSuite applications not only fortifies the security of sensitive data but also aligns with the best practices for data protection and privacy. By leveraging https.createSecretKey for encryption and https.createSecureString for decryption, developers can assure that customer data is handled securely and responsibly, in accordance with industry standards and regulations.

Thank you for tuning into our blog. We’re excited to share more tips and tricks to help you navigate the world of NetSuite development securely and efficiently.

Until next time, code safely and smartly.

Radek Felkl

SDN Solutions Engineer EMEA

With many years of experience, he has been dedicated to guiding partners in discovering the most effective methods for developing their SuiteApp or integration.

Previous Post

SuiteCloud SDK And Testing SuiteApps with JEST

Federico Donner | 7 min read

Next Post

Getting Started with SuiteScript 2.1, TypeScript, and the SuiteCloud Development Framework (SDF)

Mohammed Kassem | 6 min read