OAuth 2.0 for Web Server Applications

OAuth 2.0 Support

The Procore OAuth 2.0 implementation currently supports the Authorization Code Grant flow (most common flow). This flow is very secure and is the preferred choice for web server applications.

Step 1: Redirect to Procore Login

First, redirect your users to https://app.procore.com/oauth/authorize through a GET request. This is the result of some action in your application (e.g., the user clicks on ‘Connect with Procore’).

Use the following parameters to make your request:

Parameter Description
response_type (required) Specifies whether the endpoint returns an authorization code. For web applications, use a value of ‘code’.
client_id (required) The client_id you obtained in the Developer Portal when you created your application.
redirect_uri (required) The redirect URI is the URL within your application that will receive OAuth 2.0 credentials. By default, the redirect URI of your application is set to http://localhost in the Developer Portal. You should configure your port and relative path based on your application (e.g., http://localhost:8080/oauth/procore/callback can be used for development).

A sample GET request will look like this:

Request Method: GET

Request URL: https://app.procore.com/oauth/authorize?response_type=code&client_id=<YOUR_CLIENT_ID>&redirect_uri=<YOUR_REDIRECT_URI>

At this point, the user is forwarded to Procore’s Login page:

Procore Login

Your application does not need to do anything here - Procore handles authenticating the user and giving them feedback on any errors. After successfully logging in, the user is prompted to give your application access to their Procore account.

OAuth Prompt

After the user clicks Allow, your application receives a response from Procore, which is explained in the next section.

Step 2: Handling the Response from Procore

If the user clicked Allow in the screen shown above, Procore redirects the user to the redirect URI you specified earlier along with the authorization code. For example, if your redirect URI was http://localhost:8080/oauth/procore/callback, then Procore would redirect to:

http://localhost:8080/oauth/procore/callback?code=<AUTHORIZATION_CODE>

Note: The authorization code is valid for only 10 minutes.

Step 3: Getting the Access Token

Once your application has completed the steps outlined in the section above and received an authorization code, you will now need to exchange the authorization code for an access token from Procore.

To get the access token you make a POST request to the token endpoint with the following parameters:

Parameter Description
grant_type Use the value `authorization_code` when getting a new access token.
code The authorization code you retrieved previously.
client_id The client_id you obtained in the Developer Portal when you created your application.
client_secret The client_secret you obtained in the Developer Portal when you created your application.
redirect_uri The redirect URI is the URL within your application that will receive OAuth 2.0 credentials. By default, the redirect URI of your application is set to http://localhost in the Developer Portal. You should configure your port and relative path based on your application. (e.g., use http://localhost:8080/oauth/procore/callback for development.

Here is an example request:

Request Method: POST

Request URL: https://app.procore.com/oauth/token?grant_type=authorization_code&code=<AUTHORIZATION_CODE>&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&redirect_uri=<YOUR_REDIRECT_URI>

If everything goes right and the request is successful, you’ll receive a 200 response containing a JSON body like this:

{ "access_token": "dbaf9757982a9e7...", "token_type": "bearer", "expires_in": 7200, "refresh_token": "76ba4c5c75c96f608...", "created_at": 1484786897 }

Note: Be sure to retain the refresh_token string in a safe place. You will need to refresh the access token.

Step 4: Using the Access Token and Showing Access Token Information

Once you have retrieved an Access Token as described in the previous step, you can use it to make calls to the Procore Connect API. In order successfully make calls to the API you must include the Access Token as part of the request header using the syntax: Authorization: Bearer <YOUR_ACCESS_TOKEN>.

Here is a cURL example showing a call to the List Projects endpoint in the Procore Connect API:

curl https://app.procore.com/vapid/projects?company_id=1234 -H "Authorization: Bearer a503fcf9-45c5-4edc-8224-123284a56ea4"

Though not an integral part of the authentication workflow, there may be times when using the Get Token Info endpoint can be handy for checking the status of an access token or gathering other useful details. See Get Token Info for additional information. Keep in mind that you will need to place the Access Token in the Authorization header of the request as described above.

Step 5: Refreshing the Access Token using Refresh Token

Because the access token expires after 2 hours, you will need to use the Get or Refresh an Access Token endpoint again to periodically renew it using the below parameters:

Here is an example request:

Request Method: POST

Request URL: https://app.procore.com/oauth/token?grant_type=refresh_token&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>&refresh_token=<refresh_token>

If everything goes right and the request is successful, you will receive a 200 response containing a JSON body like this:

{ "access_token": "eyJ0eXAiOiJKV1QiL...", "token_type": "bearer", "expires_in": 7200, "refresh_token": "2aa7d1e10f84504231553...", "created_at": 1484790429 }

Access Token Revocation

IMPORTANT: For security reasons, it is imperative that you implement a solution within your application or integration for revoking access tokens for Procore user accounts that become inactive or are otherwise terminated. The Procore Connect API provides the Revoke Token endpoint for handling this requirement.

The Revoke Token POST request must contain the access token you want to revoke in the Authorization header: Authorization: Bearer <YOUR_ACCESS_TOKEN>. In addition, be aware that the body data must be sent as form-data in order to hide potentially sensitive information, thereby providing an extra layer of security. If the token is revoked successfully, or if the client submits an invalid token, the authorization server responds with HTTP status code 200. The Revoke Token endpoint revokes both the access token and refresh token. See the Revoke Token reference page for additional information.