Using User Credentials for RESTlet Authentication
When you call a RESTlet, you can authenticate by providing a user ID and password. With this approach, you use an NLAuth authorization header. NLAuth is a NetSuite-specific authentication approach that is used for RESTlets only.
As of the 2021.1 release, user credentials authentication for newly created RESTlets are not supported. If you attempt to authenticate a new RESTlet, with user credentials after your account is upgraded to 2021.1, an HTTP error response is returned
Either the three-step TBA authorization flow or the OAuth 2.0 should be used for all new integrations. Developers of existing integrations currently using the issuetoken endpoint should consider migrating the integration to the TBA authorization flow. For information, see the following:
-
OAuth 2.0 for Integration Application Developers for OAuth 2.0.
If you are calling a RESTlet from an external source, you must authenticate by using token-based authentication or OAuth 2.0. For details on TBA, see Using TBA for RESTlet Authentication (OAuth). For details on OAuth 2.0, see Using OAuth 2.0 for RESTlet Authentication.
Required Data
To construct an NLAuth authorization header, you use the fields described in the following table.
Strings must be escaped using RFC 5849. If you do not escape characters in the header, you may receive an INVALID_LOGIN_ATTEMPT error. For more information about percent encoding, see https://tools.ietf.org/html/rfc5849#section-3.6.
|
Field |
Description |
Required? |
Notes |
|---|---|---|---|
|
nlauth_account |
The ID of the NetSuite account where the RESTlet is deployed. |
Yes |
— |
|
nlauth_email |
The email address with which the user logs in to NetSuite. |
Yes |
— |
|
nlauth_signature |
The user’s password. |
Yes |
— |
|
nlauth_role |
The internal ID of a role with which the user is associated. |
No |
If you omit this value, the system selects a role based on the logic described in RESTlet and SOAP Web Services Role Selection Logic. |
|
nlauth_application_id |
The application ID of the integration associated with the RESTlet. |
No |
The application ID is optional, but you should use it. By adding an application ID, you associate RESTlet requests with a specific integration. By associating your RESTlets with an integration record, you can take advantage of the benefits of integration records. The benefits include support for viewing details about your integration applications, blocking an application, and viewing the execution log specific to each application. For more information, see Integration Record Overview. |
|
nlauth_otp
Important:
This parameter can only be used with the issue token endpoint. |
The value of the one-time password (OTP) is the same as the value of a two–factor authentication (2FA) verification code generated by an authenticator app when a user is logging in to the NetSuite UI. |
No |
For the issue token endpoint, including the nlauth_otp parameter in the NLAuth authorization header permits the sending of an OTP. The OTP is a 2FA verification code. For more information, see the following topics: |
RESTlet and SOAP Web Services Role Selection Logic
As of 2017.1, the logic for how a role is selected when no role is specified in the request changed. This change does not affect logins where a role is provided.
This type of login is possible for each of the following:
-
RESTlet calls that use an NLAuth authorization header
-
SOAP web services requests that use the following login approaches:
-
the login operation
-
request-level credentials with the Passport complex type
-
If a Customer Center role must be used in an integration, you should explicitly specify the role. If no role is specified, the system chooses a role. The system tries to use a non-Customer Center role. If there are no available non-Customer Center roles, login is attempted with a Customer Center role. The overall order of role selection is:
-
The role specified by the request.
-
If the request is a SOAP web services request, the default web services role for the user, if one exists. Default SOAP web services roles are listed on the SOAP Web Services Preferences page (at Setup > Integration > SOAP Web Services Preferences). This role can be a Customer Center or non-Customer Center role.
-
The default role for the user for the account, if the default role is a non-Customer Center role.
-
The last non-Customer Center role that the user logged in with.
-
The default role for the user for the account, if the default role is a Customer Center role.
-
The last Customer Center role that the user logged in with.
RESTlet authentication accepts special characters only if they are URL encoded. If your credentials contain special characters, replace each special character with its appropriate URL encoding. For additional information about URL encoding, see http://www.w3schools.com/tags/ref_urlencode.asp.
Syntax
The NLAuth header requires the following elements:
-
The prefix
NLAuth, followed by a space. -
A series of field-value pairs. Each pair should include the field name, an equals sign, and a value. Separate the pairs by commas. You should enter the key-value pairs without leading or trailing spaces. For example, nlauth_account=123456, rather than nlauth_account= 123456 ,
Examples
The following sample shows a correctly formatted NLAuth header.
Authorization: NLAuth nlauth_account=123456, nlauth_email=jsmith@example.com, nlauth_signature=xxxx, nlauth_role=37, nlauth_application_id=12345ABC-123A-456B-789C-123456789ABC
The following sample shows a correctly formatted NLAuth header when using the token endpoint. The header includes a verification code (an OTP for passing a 2FA challenge) using the nlauth_otp parameter.
Authorization: NLAuth nlauth_account=123456, nlauth_email=jsmith@example.com, nlauth_signature=xxxx, nlauth_role=37, nlauth_otp=654321
For an example of a shell script that generates an NLAuth header, see Example of a Shell Script that Calls a RESTlet.