Issue Token and Revoke Token REST Services for Token-based Authentication

You can call a token endpoint to issue a token, to revoke a token, and to obtain information about a token. See the following sections:

Important:

 You can use TBA with those integrations that require the Administrator role. Administrators can only create tokens for their own use by clicking the Manage Access Tokens link in the Settings portlet, or by using the token endpoint. 

In addition to creating a token manually through the NetSuite UI, developers and users can issue or revoke their own tokens programmatically using a token endpoint. You can also use a token endpoint to obtain information about a token.

Use the appropriate domain to call the token endpoint:

Users cannot programmatically issue or revoke tokens for other users using a token endpoint. For information about creating tokens for other users through the NetSuite UI, see Viewing, Editing, Creating, and Revoking TBA Tokens.

Account-specific domains are supported for RESTlets. For example, if your account ID is 123456, your account-specific REST domain would be 123456.restlets.api.netsuite.com. For more information, see URLs for Account-Specific Domains. See also the Integration Domains section in the topic How to Transition from Data Center-Specific Domains.

Important:

Whether using The Three-Step TBA Authorization Flow, or calling The IssueToken Endpoint, an integration record is created and automatically installed in your account. The Require Approval during Auto-Installation of Integration preference affects whether this new record is automatically enabled. You can manage the preference at Setup > Integration > SOAP Web Services Preferences. If the Require Approval during Auto-Installation of Integration box is not checked (set to false) the State field on the new application is automatically set to Enabled, and all requests are permitted. However, if the box is checked (set to true) the State field on the new integration record is set to Waiting for Approval. In the latter case, you must manually edit the record and set the State to Enabled. Until you set the state to Enabled, all requests sent by that application are blocked.

Calling a token endpoint to issue a token

  • Use the NetSuite NLAuth authorization header. The token is created under the role specified in the NLAuth authorization header. For more information, see Using User Credentials for RESTlet Authentication.

  • Parameters must be Url encoded. This is particularly important for parameters which include special characters like spaces, for example, token name.

  • A token endpoint consumes two GET parameters. For an issuetoken request, the Consumer Key parameter is mandatory, and the Name (the name of the token) is optional.

    For example:

                    https://<accountID>.restlets.api.netsuite.com/rest/issuetoken?consumerKey=<CONSUMER_KEY>&name=<TOKEN_NAME> 
    
                  
  • The issue token endpoint has been extended to accommodate the requirement for mandatory 2FA for highly privileged roles. There is an optional parameter, nlauth_otp, that you can include in the NLAuth Authorization header. For more information, see Mandatory 2FA, the IssueToken Endpoint, and nlauth_otp.

Calling a token endpoint to revoke a token

  • In a call to a token endpoint to revoke a token, use either:

  • A token endpoint consumes two GET parameters. For a revoketoken request, both the consumerKey parameter and the token parameter are mandatory.

    Here is an example of a request: https://<accountID>.restlets.api.netsuite.com/rest/revoketoken?consumerKey=<CONSUMER_KEY>&token=<TOKEN>

Calling a token endpoint to obtain user information based on a token

The tokeninfo endpoint returns information about a user based on the access token. The endpoint is https://<accountID>.restlets.api.netsuite.com/rest/tokeninfo, where <accountID> is a variable for the company’s account ID. A response to a GET request contains data in JSON format, including information such as:

  • Company Name

  • Company ID (account ID)

  • Role Name

  • Role ID

  • Entity ID

Related Topics

Authentication
RESTlets vs. Other NetSuite Integration Options
The REST Roles Service
DataCenterUrls REST Service

General Notices