The REST Roles Service

NetSuite provides a REST service called roles, which you can use to retrieve the following information:

A list of roles assigned to the user.
The correct domains for external client access to a NetSuite account. In an integration, domains must be discovered dynamically, because they can change without notice.
The account type of the returned account (for example, production, Release Preview, or sandbox account).

Note:

As of 2020.1, when you call the REST roles service on an account-specific domain, only the account-specific information is returned. All roles are returned for the user, including the Customer Center roles, and any roles created based on the Customer Center role.

Note:

RESTlets are part of SuiteScript. They are not part of the NetSuite web services feature. Be aware that if a role has the Web Services Only option set to true, a user logged in through that role is permitted to send web services calls only. RESTlet calls receive an INVALID_LOGIN_CREDENTIALS error response.

You call the roles service by sending a request to one of the roles service URLs, as described in URLs for Accessing the REST roles Service. The request must use the GET method, and it must also include an NLAuth authorization header. For details, see Authentication for the REST roles Service. If you need to retrieve Customer Center roles, note that you must include a NetSuite account ID in the authorization header.

In response, the service returns data about roles and domains. For examples, see Sample Responses from the roles Service.

Note:

Using the REST roles service is not an authentication method. Accessing the REST roles service is not considered as a login. This service only returns the list of roles for a user, but does not log the user in.

For specific details on domain data returned by the roles service, see Domain Data Returned by the roles Service.

For information about NLAuth, see Using User Credentials for RESTlet Authentication.

Account-specific domains are supported for RESTlets. Account-specific domains contain the account ID as part of the domain name. An account-specific domain is not dependent on the data center where the account is hosted. The domain does not change, even if the account is moved to a different data center. Your account-specific domain for RESTlets is shown on the Company Information page on the Company URLs subtab. For more information, see URLs for Account-Specific Domains. Use your account-specific domain for RESTlets.

Currently, HTTP GET requests using obsolete data center-specific domains are redirected, but this redirection is temporary and may end at any time.

Important:

If you have an integration that makes requests to the production version of the roles service, and these requests are specific to a NetSuite account, your integration must include logic for handling redirection. This logic is necessary because of how the system handles requests specific to a NetSuite account. NetSuite redirects these calls to the instance of the service specific to the data center that hosts the account. For this reason, your integration must include logic for handling the 302 Found response status code, which is the code used when redirection occurs. By contrast, if your authorization header omits a NetSuite account ID, the request is handled without redirection.

Related Topics