Handling Procore Regions

Background

As part of an ongoing infrastructure improvement initiative, we’ve established Multiple Procore Regions (MPR) in our network topology. MPR allows us to distribute our customer load across a larger pool of infrastructure to provide better scalability, durability, and security. With MPR in place, we can distribute our infrastructure over multiple geographical locations. With the rollout of MPR, you will need to adhere to specific implementation requirements and best practices when building solutions with the Procore API. These requirements and best practices are presented in the following sections.

MPR Architecture

The following diagram serves to illustrate the new MPR architecture. The connections between the components are sequentially numbered and are annotated with the relevant attributes of the API requests/responses involved in obtaining an access token (steps 1-4) and using that access token to subsequently make a call to a Procore resource (steps 5-8).

MPR Architecture Diagram - 01

Required Changes

In order for your application to be compliant with the new MPR architecture, you will need to implement a number of changes as described below.

New Base Domain for OAuth 2.0 Authentication Requests - The base domain for OAuth 2.0 Authentication endpoints has been changed from app.procore.com to login.procore.com. As a result, all authentication-related requests (i.e., requesting an authorization code, retrieving an access token, and refreshing an access token) must use login.procore.com as their base domain.
New Base Domain for Procore API Endpoints - The base domain for Procore API endpoints has been changed from app.procore.com to api.procore.com. As a result, you will need to ensure that all the Procore API calls you make from your application to the production Procore environment use this new base domain.
New Request Header Requirement - Each call your application makes to the Procore API must contain a request header that includes the Procore-Company-Id field. This request header field specifies the id of the company into which you are making the call. Here is a cURL example showing a call to the List Projects endpoint.

curl -H "Authorization: Bearer <access token>” -H "Procore-Company-Id: xxxxxxxxx"
     -X GET https://api.procore.com/rest/v1.0/projects?company_id=xxxxxxxxx

In this example, we use -H flags to specify the Authorization and Procore-Company-Id request header fields. It is important to note that even though an endpoint might require the company_id as a path or query parameter, MPR still requires you to include the Procore-Company-Id field in the request header.

If you do not supply the required request header, the following error message is displayed.

Missing Procore-Company-Id header!

Each call your application makes to the Procore API must contain a request header that includes the Procore-Company-Id field. 
This request header field specifies the id of the company into which you are making the call.

Note: The following Procore API endpoints do not require a request header containing the Procore-Company-Id field:

Show User Info - (GET /rest/v1.0/me)
List Companies - (GET /rest/v1.0/companies)

The exception to this rule is when you are using Service Accounts with the OAuth 2.0 Client Credentials grant type. See Using Service Accounts with MPR for additional information.

Requirements

All applications accessing the Procore API must be MPR-compliant. The Procore-Company-Id request header is required on all API calls (with the exception of the endpoints listed above). Applications that do not include this header will not be able to access data for Procore customers.

Resource ID Value Size

With the introduction of Multiple Procore Regions (MPR), the size of resource ID values in any new Procore region may exceed what can be stored in a 32-bit integer. Ensure that you store ID values using a data type capable of storing 64-bit integers or larger, such as BigInt, int64_t, or long long depending on your coding language/framework.

Frequently Asked Questions

Will the MPR architecture changes impact my sandbox environments?

Answer: Yes. Sandbox environments also require MPR-compliant API calls, including the Procore-Company-Id request header. For sandbox environment URLs and setup details, see Sandbox Environments.

Need Additional Information?

If you have any questions or need help in determining the impacts of MPR on your application codebase, please contact our Technical Services team for assistance.