OAuth 2.0 for Integration Applications Developers

OAuth 2.0 Endpoints URL Schema and Account-Specific URLs

For each step of the OAuth 2.0 authorization code flow, you must send requests to the authorization server using URLs specific to each type of request.

The following URL shows how you construct a request URL:

https://<account-domain>/login/oauth2/v1/<endpoint><query-string>

• The first part of the URL must include your account-specific domain <account-domain> and the service path for OAuth 2.0. For more information about your account-specific domain name, see Your Account URLs.

• The second part of the URL depends on the endpoint you want to access

  <endpoint>	Description
  authorize	Use the authorization endpoint to get the user’s explicit permission and receive an authorization code in response if the user authorizes the app to access SuiteProjects Pro on their behalf. The request URL includes a query string with request parameter. https://<account-domain>/login/oauth2/v1/authorize?<query-string> See Getting the User’s Permission and Receiving the Authorization Code.
  token	Use the token endpoint to exchange the authorization code for an access token or to refresh an access token. Request parameters are passed in the request headers and body. https://<account-domain>/login/oauth2/v1/token See Exchanging the Authorization Code for an Access Token and Refreshing an Access Token.

Getting the User’s Permission

To begin the OAuth 2.0 authorization code flow, the client application must direct the user to the authorization server — SuiteProjects Pro — using a GET request.

Send a GET request to the authorization endpoint using a URL like the following example:

https://company-id.app.netsuitesuiteprojectspro.com/login/oauth2/v1/authorize?response_type=code&redirect_uri=https://example-app.com/redirect&client_id=client_application_id&scope=xml+soap+rest&state=client_generated_string 

Replace the account domain and parameter values https://example-app.com/redirect, client_application_id and client_generated_string given in the example using the following guidelines.

The GET request URL includes the authorization endpoint for the SuiteProjects Pro account followed by a query string:

https://<account-domain>/login/oauth2/v1/authorize?<query-string>

where <account-domain> is your account-specific domain name. For more information, see Your Account URLs.

The request parameters are described in the following table.

After the application sends the GET request, SuiteProjects Pro redirects the user to the SuiteProjects Pro sign-in page. SuiteProjects Pro may redirect the user to a third-party Identity provider Single Sign-on form, if SAML SSO is enabled for the account and the user. After successful authentication, SuiteProjects Pro shows an authorization page prompting the user to approve the application’s access request.

Receiving the Authorization Code

After obtaining the user’s explicit permission, SuiteProjects Pro initiates a redirect to the redirect URI specified in the GET request with the authorization code and the state as query parameters.

The redirect query parameters are described in the following table.

The following sample redirects illustrate successful and unsuccessful authorization.

• Application successfully authorized.

  https://example-app.com/redirect?state=client_generated_string&code=authorization_code 
  

  https://example-app.com/redirect?state=ryjp37y2qa28hdseck1gat&code=JTlQ43UvYDKbhI_SpEWsIE_bTpbou2-kYeeLtKiMuR1iqZ3W3roqM4rmRC8fFCOJtBI6a85AnJPefx2szW9g4jCY

• Application not authorized.

  https://example-app.com/redirect?error_description=The+resource+owner+or+authorization+server+denied+the+request&error=access_denied&state=client_generated_string 
  

  https://example-app.com/redirect?error_description=The+resource+owner+or+authorization+server+denied+the+request&error=access_denied&state=ryjp37y2qa28hdseck1gat

where:

• client_generated_string is the same string that was sent in the request using the state parameter.

• authorization_code is the OAuth 2.0 authorization code obtained for a specific client application and a specific user.

Exchanging the Authorization Code for an Access Token

The application can use the authorization code to obtain an access token and a refresh token using a POST request.

Send a POST request to the token endpoint.

• The POST request URL is https://<account-domain>/login/oauth2/v1/token

• The request must include the client ID and the client secret in the HTTP authorization request header.

  • The client authentication method used in a header of the request follows the HTTP Basic authentication scheme. For more information, see RFC 7617.

  • The format is client_id:clientsecret.

  • The string value is Base64 encoded.

• The request must include the parameters grant_type, code and redirect_uri in the request body.

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

The request parameters are described in the following table.

Example POST request:

              POST /login/oauth2/v1/token HTTP/1.1
Host: company-id.app.netsuitesuiteprojectspro.com
Authorization: Basic base_64_encoded_client_id:client_secret
Content-Type: application/x-www-form-urlencoded
code=authorization_code&redirect_uri=https%3A%2F%2Fexample-app.com%2Fredirect&grant_type=authorization_code 

            

Replace the following values in the example:

• base_64_encoded_client_id:client_secret with the base 64 encoded string required to authenticate the request, which includes the client ID and client secret.

• authorization_code with the OAuth 2.0 authorization code obtained for a specific client application and a specific user.

• https%3A%2F%2Fexample-app.com%2Fredirect with the URL-encoded redirect URI for the client application.

The token endpoint will verify all the parameters in the request to ensure that the authorization code is valid and that the client ID and client secret match. If all the request headers and parameters are valid, the token endpoint generates an access token and refresh token and includes them in the response.

The token endpoint returns the response as a JSON object with the properties described in the following table.

Example response (successful token request):

              HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
      "refresh_token":"OAuth2_refresh_token",
      "expires_in":900,
      "access_token":"OAuth2_access_token",
      "token_type":"bearer"
} 

            

In the example, OAuth2_access_token is the OAuth 2.0 access token obtained for the client application that is used to authenticate API requests, and OAuth2_refresh_token is the OAuth 2.0 refresh token obtained for the client application that is used to request a new access token when it expires.

If the request fails, the token endpoint returns a JSON object with the error and error_descrtiption properties. See Token Request Errors.

The client application can now use the access token to make API requests. This completes the authorization flow.

The access token is only valid for a short period of time and within the scope it was issued for. The client application will need to refresh the access token to continue making API requests after it expires.

Refreshing an Access Token

The access token has a short expiration time (15 minutes). When the access token expires, the client application can use the refresh token to obtain a new access token using a POST request.

• You can use the expiration time value (expires_in) to refresh access tokens before it is due to expire.

• You can refresh access tokens if an API request returns an authentication failed error.

• Each refresh token can be used one time only. Refresh in an access token generates a new access token and a new refresh token.

Send a POST request to the SuiteProjects Pro token endpoint. The POST request is similar to that used to exchange an authorization code for an access token except it now uses the parameters set in the following table.

Example POST request:

              POST /login/oauth2/v1/token HTTP/1.1
Host: company-id.app.netsuitesuiteprojectspro.com
Authorization: Basic base_64_encoded_client_id:client_secret
Content-Type: application/x-www-form-urlencoded
refresh_token=OAuth2_refresh_tokenredirect_uri=https%3A%2F%2Fexample-app.com%2Fredirect&grant_type=refresh_token 

            

Replace the following values in the example:

• base_64_encoded_client_id:client_secret with the base 64 encoded string required to authenticate the request, which includes the client ID and client secret.

• OAuth2_refresh_token with the OAuth 2.0 refresh token obtained for the client application.

• https%3A%2F%2Fexample-app.com%2Fredirect with the URL-encoded redirect URI for the client application.

The token endpoint will verify all the parameters in the request to ensure that the refresh token is valid and that the client ID and client secret match. If all the request headers and parameters are valid, the token endpoint generates an access token and refresh token and includes them in the response.

The token endpoint returns the response as a JSON object with the properties described in the following table. The response includes both a new access token and a new refresh token.

Example response (successful token request):

              HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
      "refresh_token":"OAuth2_refresh_token",
      "expires_in":900,
      "access_token":"OAuth2_access_token",
      "token_type":"bearer"
} 

            

In the example, OAuth2_access_token and OAuth2_refresh_token are the new OAuth 2.0 access token and the new OAuth 2.0 refresh token obtained for the client application.

If the request fails, the token endpoint returns a JSON object with the error and error_descrtiption properties. See Token Request Errors.

Token Request Errors

Your client application needs to handle the following cases when the request to exchange an authorization code for an access token or to refresh a token fails. The token endpoint may return one of the errors listed in the following table if the token request fails.

• Errors are listed in descending priority order. Only the first error is returned if there are more than one.

• Some of the errors are specific to one of the two possible types of request ( grant_type).

Authorization Errors

The relevant licensed add-on features must be enabled in your account:

• API access must be enabled except if you are using the REST API to access supported Business Intelligence (BI) Connector resources.

• The BI Connector feature must be enabled if you are using the REST API to access supported Business Intelligence (BI) Connector resources. The REST API returns HTTP status 404 Not found with error message Page not found or Report not found if you attempt to access a BI Connector resource endpoint with a valid access token and the BI Connector feature is disabled.

API requests must use a valid access token with a valid scope.

• The access token must exist.

• The access token must not be expired.

• The user who gave the application permission to access SuiteProjects Pro must be active. The same access token can be used if the user is set to active again.

• The application must be enabled in the SuiteProjects Pro account. The same access token can be used if the application is disabled and then enabled again.

• The access token must be used within the scope it was issued for. For example, if the authorization code was obtained for the scope xml+rest, the client application cannot use the access token in a SOAP API request.

The error code and message returned depend on the API:

• The XML API returns error code 420 and message Authentication failed.

• The SOAP API returns error code 9 and message Logged out.

• The REST API returns HTTP status 401 Unauthorized and the response includes a WWW-Authenticate header error="invalid_token", error_description="The access token is invalid".

An invalid OAuth 2.0 access token authorization has priority over a valid password authentication. You cannot use password authentication (Company ID, User ID, password) — or a valid Session ID in the SOAP session header — as a fallback for an invalid access token.