NetSuite’s N/keyControl module is a powerful but often overlooked part of SuiteScript. It allows developers to securely create, load, delete, and manage SSH keys directly through SuiteScript — the same keys used for SFTP integrations and secure external file transfers.

If you’re building integrations using the N/sftp module, understanding the N/keyControl module is essential.

In this guide, we cover:

• What the N/keyControl module does
• All available methods and their use cases
• How to store and manage SSH keys
• How to create and load keys programmatically
• When and why to lock keys
• How key restrictions and security work

Let’s get started.

⭐ 1. What Is the N/keyControl Module?

The N/keyControl module gives developers access to NetSuite’s internal key storage system.

You can use it to:

✔ Create SSH keys
✔ Load existing keys
✔ Delete (soft delete) keys
✔ Restrict access to employees
✔ Lock/unlock keys to prevent UI edits
✔ Find all stored keys
✔ Use keys for SFTP connections via N/sftp

You can also manage keys manually in the UI at:

Setup → Company → Preferences → Keys

⭐ 2. Why This Module Matters (Real Use Cases)

The N/keyControl module is critical for:

• Automated file transfers (SFTP)
• Integration with 3PL, EDI, logistics, banking, etc.
• Replacing password-based authentication with key-based access
• Managing SSH keys securely inside NetSuite
• Programmatic rotation of old keys

Instead of hardcoding SSH keys into scripts, NetSuite stores them securely and allows controlled access — a major improvement in security best practices.

⭐ 3. Key Module Members (Methods & Objects)

The N/keyControl module exposes several functions. Here’s what each one does.

🔹 keyControl.findKeys(options)

Returns: List of stored keys
Use case: Search for keys based on filters

If no criteria are provided, it returns all keys stored in NetSuite.

Example filters include name, scriptId, or restrictions.

🔹 keyControl.createKey(options)

Returns: keyControl.Key object
Use case: Create a NEW SSH key in NetSuite

You can specify:

• File object (actual private key)
• Password (if applicable)
• Script ID
• Description
• Restrictions

After creation, you call key.save().

🔹 keyControl.deleteKey(options)

Returns: Object
Use case: Soft-delete a key

Keys are not permanently removed — history remains for auditing.

🔹 keyControl.loadKey(options)

Returns: keyControl.Key object
Use case: Retrieve an existing SSH key by scriptId

This is required for loading a key before passing it to the N/sftp module.

🔹 keyControl.lock(options)

Returns: String
Use case: Prevents the key from being modified in the UI

Helpful for production environments to prevent accidental editing.

🔹 keyControl.unlock(options)

Returns: String
Use case: Unlocks a previously locked key

Needed when rotating keys or updating file/password.

🔹 keyControl.Operator (Enum)

Used for filtering keys when calling findKeys.

⭐ 4. Key Object Members

When you load or create a key, you interact with the keyControl.Key object.

Here are the available properties:

📌 Key.file (file.File object)

The actual private key file stored in the File Cabinet.

📌 Key.password (string)

Write-only password (if key requires passphrase).

You can pass:

• Plain text
• API Secret Script ID
• GUID from a secret key field

📌 Key.scriptId (string)

Unique script ID — NetSuite prepends custkey automatically.

📌 Key.name (string)

Human-readable name for the key.

📌 Key.description (string)

Optional description.

📌 Key.restrictions (string)

Internal IDs of employees allowed to access the key.

📌 Key.save()

Saves your changes (create or update).

⭐ 5. Example: Creating a New SSH Key in SuiteScript

define(['N/keyControl', 'N/file'], function(keyControl, file) {

    function createSSHKey() {
        var keyFile = file.load({ id: 'SuiteScripts/keys/sftp_private_key.key' });

        var newKey = keyControl.createKey({
            scriptId: 'my_sftp_key',
            name: 'SFTP Private Key',
            description: 'Key for external SFTP server',
            file: keyFile,
            password: 'myKeyPassphrase'
        });

        var result = newKey.save();
        log.debug('Key Created', result);
    }

    return { execute: createSSHKey };
});

⭐ 6. Example: Loading a Key for SFTP

var keyObj = keyControl.loadKey({ scriptId: 'custkey_my_sftp_key' });

var connection = sftp.createConnection({
    username: 'ftpuser',
    host: 'ftp.example.com',
    keyId: keyObj.scriptId
});

NetSuite automatically retrieves the private key for authentication.

⭐ 7. Locking & Unlocking Keys (Security Control)

Lock a Key:

keyControl.lock({ scriptId: 'custkey_my_sftp_key' });

Unlock a Key:

keyControl.unlock({ scriptId: 'custkey_my_sftp_key' });

This is crucial for securing production keys.

⭐ 8. Best Practices for Using N/keyControl

✔ Never store SSH keys as script files

Always store in Key Management → Keys.

✔ Use key locking in production

Prevents accidental or unauthorized edits.

✔ Rotate keys regularly

Improve your integration security.

✔ Restrict keys to specific employees

Use the “Restrict to Employees” feature.

✔ Do NOT log key data

Avoid printing key contents in script logs.

✔ Pair with N/sftp for secure file management

N/keyControl + N/sftp is the recommended combination.

⭐ 9. Final Thoughts

The N/keyControl module is essential for anyone working with secure file transfers, third-party integrations, and SFTP automation within NetSuite.

It gives developers:

• Secure key storage
• Full SuiteScript access
• Programmatic key rotation
• Clear permissions control
• Production-ready locking

If you’re building integrations, this module must be part of your toolkit.