OAuth 2.0 for Installed Applications
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
https://app.procore.com/oauth/authorize endpoint with the following parameters:
|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|
GET request will look like this:
At this point the user is forwarded to Procore’s login page:
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
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.
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.