Authentication

The REST API supports authentication by OAuth 2.0 bearer token exclusively. You must send the OAuth 2.0 access token as a bearer token in the Authorization header for each request.

Integration applications must be registered in SuiteProjects Pro to use the REST API to access SuiteProjects Pro data, and users must give the application explicit permission to access SuiteProjects Pro on their behalf.

For more information about using the OAuth 2.0 authorization framework, see OAuth 2.0 Authorization.

Important:

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Note:

The API uses cached filter set information —information about objects which the authenticated user can access according to the filter set assigned to that user— to optimize performance. By default, GET requests using a valid access token do not return objects created after the access token was issued in the response, even if the user can access the new objects in the UI. If new objects are expected, you can clear and regenerate the cached filter set information by sending a POST request to the filter set cache refresh endpoint. Subsequent GET requests to resource endpoints return the latest available data including any objects that were created recently. See Filter Set Cache Refresh.

Example

The following request sends a bearer token in the Authorization header.

            GET /rest/v1/job-codes/ HTTP/1.1
Host: company-id.app.netsuitesuiteprojectspro.com
Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application connecting to SuiteProjects Pro.

Authentication Errors

Your client application needs to handle the following cases when the authentication may fail. The REST API may return one of the errors listed in the following table if the authentication fails. The response includes a HTTP Status and WWW-Authenticate header with information about the error.

`HTTP Status`	`WWW-Authenticate Header`	Reason
400 Bad request	error="invalid_request", error_description="Invalid Bearer token format"	The Authorization header sent in the request must have the correct format for Bearer token authentication. For example, a missing space between “Bearer” and the token would cause a `400 Bad Request` error.
401 Unauthorized	error="insufficient_scope", error_description="The access token is invalid"	The bearer token sent in the request is not valid. Possible reasons include: Invalid scope — Tokens are issued for a specific `scope`. The scope of the access token does not allow access to the resource endpoint using the REST API. The scope must include `rest` to access SuiteProjects Pro resources other than Business Intelligence (BI) Connector resources. The scope must include `bi` to access BI Connector resources.
401 Unauthorized	error="invalid_token", error_description="The access token is invalid"	The bearer token sent in the request is not valid. Possible reasons include: Expired access token — Access tokens are valid for the period specified in the application configuration in SuiteProjects Pro. Authorization revoked — Users can revoke an application at any time. Disabled application — Account administrators can disable an application at any time. Application removed — Account administrators can remove an application at any time. Access not allowed for the client IP address — The IP Restriction feature is enabled for the SuiteProjects Pro account and the client IP address is not in the allowlist for the user associated with the bearer token. Disabled feature — The feature required to access the resources is not enabled for your account. API Access and REST API must be enabled for your account to access SuiteProjects Pro resources other than Business Intelligence (BI) Connector resources. The BI Connector feature must be enabled for your account to access BI Connector resources. API access and REST API are not required.

HTTP Status

WWW-Authenticate Header

Reason

400 Bad request

error="invalid_request", error_description="Invalid Bearer token format"

The Authorization header sent in the request must have the correct format for Bearer token authentication. For example, a missing space between “Bearer” and the token would cause a 400 Bad Request error.

401 Unauthorized

error="insufficient_scope", error_description="The access token is invalid"

The bearer token sent in the request is not valid. Possible reasons include:

Invalid scope — Tokens are issued for a specific scope. The scope of the access token does not allow access to the resource endpoint using the REST API.
- The scope must include rest to access SuiteProjects Pro resources other than Business Intelligence (BI) Connector resources.
- The scope must include bi to access BI Connector resources.

401 Unauthorized

error="invalid_token", error_description="The access token is invalid"

The bearer token sent in the request is not valid. Possible reasons include:

Expired access token — Access tokens are valid for the period specified in the application configuration in SuiteProjects Pro.
Authorization revoked — Users can revoke an application at any time.
Disabled application — Account administrators can disable an application at any time.
Application removed — Account administrators can remove an application at any time.
Access not allowed for the client IP address — The IP Restriction feature is enabled for the SuiteProjects Pro account and the client IP address is not in the allowlist for the user associated with the bearer token.
Disabled feature — The feature required to access the resources is not enabled for your account.
- API Access and REST API must be enabled for your account to access SuiteProjects Pro resources other than Business Intelligence (BI) Connector resources.
- The BI Connector feature must be enabled for your account to access BI Connector resources. API access and REST API are not required.