OAuth 2.0 for Installed Applications

Overview

If your application is an installed application (without a browser) for running cron jobs, scripts etc, it is not possible for the web browser to redirect back to your application. In that case, set your redirect URI to urn:ietf:wg:oauth:2.0:oob when you create your app. This value signals to the Procore Authorization Server that the authorization code should be returned in the url along with the page text prompting the user to copy the code and paste it in the application.

The flow for installed applications is similar to the OAuth 2.0 Web Server flow except for a few differences which are explained below:

Step 1: Redirect to Procore Login

In order to get the authorization code from Procore, you will need to make a GET request to https://app.procore.com/oauth/authorize endpoint with the following parameters:

Parameter Description
response_type (required) Specifies whether the endpoint returns an authorization code. For installed 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. The redirect URI for installed applications is urn:ietf:wg:oauth:2.0:oob

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=urn:ietf:wg:oauth:2.0:oob

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.

Step 2: Obtain Authorization Code

After successfully logging in, the Procore Authorization Server returns the authorization code in the url (https://app.procore.com/oauth/authorize/<AUTHORIZATION_CODE>) along with the page text prompting the user to copy the code and paste it into the application.

OAuth Code

Note that this authorization code is set to expire in 10 minutes. Once you were able to grab the authorization code, you need to use the authorization code in your application and exchange them for access tokens. This is explained from Step 3 onward in OAuth 2.0 for Web Server Applications.

How can my installed application go through the OAuth flow without any user interaction?

While our installed application configuration does allow for authentication without any user input, that is after the initial Grant App Authorization step is completed with user input. Once you manually go through that step by logging in and getting an authorization code, you can then programmatically authenticate from that point forward without user intervention.

After the initial App Authorization Grant, you can retrieve a pair of tokens - an Access Token and a Refresh Token. The Access Token is used to authenticate (passed with the request header as Authorization: Bearer <YOUR_ACCESS_TOKEN>), and it expires after 2 hours. The Refresh Token, which corresponds to that Access Token, will not expire until it is used to acquire a new pair of tokens. Using those two tokens, you can authenticate endlessly without any user input. In other words, after getting your first pair of tokens, your program would use the Access Token for up to 2 hours, after which that token would expire. After that token expires, the next time your program wanted to access our API it would use the Refresh Token received with the now-expired Access Token to refresh the Access Token and get a new pair of tokens. Once it makes that call, your old Refresh Token would expire since it has now been used and you would have a new Access Token and Refresh Token. Then, your program would use that new Access Token until it expires, and the cycle would repeat again.