1. Account Administration
  2. Authentication
  3. OAuth 2.0
  4. OAuth 2.0 for Integration Application Developers
  5. OAuth 2.0 Authorization Code Grant Flow
  6. Step One GET Request to the Authorization Endpoint

Step One GET Request to the Authorization Endpoint

In the first step of the OAuth 2.0 authorization code grant flow, the application sends a GET request to the authorization endpoint. This request must include the required parameters in the request header.

The format of the URL is:

https://<accountID>.app.netsuite.com/app/login/oauth2/authorize.nl.

where <accountID> represents your NetSuite account ID. If you do not know the specific account ID, requests can be sent to

https://system.netsuite.com/app/login/oauth2/authorize.nl.

See the following table for details about parameters for the GET request.

Request Parameters for Step One

Request Parameter

Description

response_type

The value of the response_type parameter is always code.

client_id

  • Identifies the client.

  • The value of the client ID is provided when the integration record is created.

redirect_uri

  • The application uses the valid redirect URI to handle the authorization code.

  • The value of the redirect URI parameter must match the redirect URI in the corresponding integration record.

scope

  • The scope for which the application is requesting access. Values are restlets, rest_webservices, suite_analytics, or all of them. If the application requests access more than one, separate the values by a white space.

  • The requested scope must be enabled in the corresponding integration record. For more information, see Create Integration Records for Applications to Use OAuth 2.0.

Note:

NetSuite supports two additional scopes that are used for the NetSuite as OIDC Provider feature. For more information, see Step One GET Request to the Authorization Endpoint in the NetSuite as OIDC Provider topic.

state

The length of the state parameter must be between 22 and 1024 characters. Valid characters are all printable ASCII characters.

Important:

To avoid cross-site request forgery (CSRF) attacks, you must conform to the OAuth 2.0 specification. For more information, see RFC6749 Section 10.12.

code_challenge

  • This parameter is optional; however, you should use this security extension.

    Important:

    If you use public clients for OAuth 2.0, the code_challenge parameter is required.

  • The code_challenge parameter is created using code_verifier, a random string of characters. For more information, see PKCE specification https://tools.ietf.org/html/rfc7636#section-4.2.

  • Apply SHA256 on the code_verifier parameter.

  • The length of the code_verifier parameter must be between 43 and 128 characters.

  • Valid characters for the code_verifier parameter are alphabet characters, numbers, and non-alpha numeric ASCII characters: hyphen, period, underscore, and tilde (- . _ ~).

code_challenge_method

  • This parameter is optional. However, if you configure the code_challenge parameter, you must configure the code_challenge_method parameter. You must use SHA256 to configure the code_challenge_method parameter.

  • When the authorization server generates an authorization code, the code_challenge and code_challenge_method parameters are associated with the authorization code value, to ensure they are properly verified. For more information, see PKCE specification https://tools.ietf.org/html/rfc7636#section-4.4.

Important:

As of 2020.2, NetSuite does not support a value of plain for the code_challenge_method parameter. Use S256 instead.

prompt

The optional prompt parameter provides additional control of when the consent screen appears. Following are the values you can use with the prompt parameter:

  • none - the consent screen does not appear. If there is no active session, the application returns an error.

  • login - the user must authenticate even if there is an active session.

    This option only works if the application sends the request to the account-specific domain.

  • consent - the consent screen appears every time. The user must authenticate if there is no active session.

  • login consent or consent login - the consent screen appears every time, and the user must authenticate even if there is an active session.

For more information, see Integration Record and Prompt Parameter Combinations.
Important:

Request parameters must be encoded based on the HTML specification for the application/x-www-form-urlencoded media type. For more information, see URL Specification 5.1.

The following URL provides a sample GET request.

            https://<accountID>.app.netsuite.com/app/login/oauth2/authorize.nl?scope=restlets+rest_webservices&redirect_uri=https%3A%2F%2Fmyapplication.com%2Fnetsuite%2Foauth2callback&response_type=code&client_id=6794a3086e4f61a120350d01b8527aed3631472ef33412212495be65a8fc8d4c&state=ykv2XLx1BpT5Q0F3MRPHb94j&code_challenge=Who5QBshz2Mu1Mq6GuAknYA5TnjA-0z7VhAgLloec1s&code_challenge_method=S256

Consent Screen

After the application sends the GET request, the system displays the consent screen, where a user authorizes the application to access NetSuite through RESTlets, REST web services, or SuiteAnalytics Connect.

Important:

If there is no active NetSuite session, the user is first redirected to the NetSuite login form. If the GET request points to an account-specific domain, for an account with SAML SSO or OIDC enabled, the user may be redirected to a third party application. After successful authentication, the system displays the consent screen.

The consent screen includes the following:

  • The Application Logo, Terms of Use, and Privacy Policy, if these values were entered in the integration record.

  • A data and a role to which the application requests access.

  • The Allow/Continue button. If the application was not previously authorized, the user must click Allow to authorize the application. If the application was previously authorized, the user must click a Continue button to continue to the next step of the flow.

  • The Deny/Go Back button. If the application was not previously authorized, the user can click Deny to interrupt the flow. If the application was previously authorized, the user can click Go Back to interrupt the flow.

  • The Choose Another Role list. The user can change a role that authorizes the application, by clicking the Choose Another Role link.

Redirect Parameters for Step One

After authorization, NetSuite initiates a redirect to the Redirect URI, with the following parameters:

Redirect Parameter

Description

state

The state parameter in the redirect must match the state parameter in the request in Step One.

code

  • A randomly generated string that is used for request verification in Step Two.

  • The code parameter is only generated if the application was authorized.

  • You must use the value of the code parameter immediately after it is generated. The value for the code parameter has limited time validity.

role

Indicates the user’s role for which the access token and refresh token are granted in Step Two.

The role parameter is a NetSuite-specific parameter.

entity

The ID of the user who authorizes the application or interrupts the flow.

The entity parameter is a NetSuite-specific parameter.

company

NetSuite account ID (company identifier).

The company parameter is a NetSuite-specific parameter.

error

The error parameter is only used when an error occurs during the flow. For information about error values, see Troubleshooting OAuth 2.0.

The following sample redirects illustrate successful and unsuccessful authorization.

  • Application successfully authorized:

                    https://myapplication.com/netsuite/oauth2callback?state=ykv2XLx1BpT5Q0F3MRPHb94j&role=1000&entity=12&company=1234567&code=70b827f926a512f098b1289f0991abe3c767947a43498c2e2f80ed5aef6a5c50

  • Application not authorized:

                    https://myapplication.com/netsuite/oauth2callback?state=ykv2XLx1BpT5Q0F3MRPHb94j&role=1000&entity=12&company=1234567&error=access_denied

After the request to the redirect URI is sent, the flow proceeds to Step Two POST Request to the Token Endpoint.

Related Topics

OAuth 2.0
OAuth 2.0 for Integration Application Developers
OAuth 2.0 Authorization Code Grant Flow
OAuth 2.0 Access and Refresh Token Structure
Troubleshooting OAuth 2.0

General Notices