Procore Connect API Authentication Endpoints

Overview

The Procore Connect API provides a set of authentication endpoints you will use to implement the OAuth 2.0 protocol in your application. In this lesson we’ll take a look at these endpoints along with their request parameters and special considerations.

Grant App Authorization (/oauth/authorize)

The Grant App Authorization endpoint creates and returns either a temporary authorization code with a 10 minute expiration, or an access token depending on the grant type. This endpoint corresponds to the OAuth 2.0 authorization endpoint described in section 3.1 of the OAuth 2.0 RFC. Three required request parameters are used with this endpoint as described in in the following table.

Parameter Description
response_type Specifies the type of response you need from the endpoint. Use a value of ‘code’ if you are using the authorization grant type flow, or use ‘token’ if you are using the implicit grant type flow.
client_id Specifies the Client ID value you were issued when you registered your application on the Developer Portal.
redirect_uri Specifies the URI that the user will be redirected to after they grant authorization to your application. For web applications applications, use an SSL (`https://`) web address. For "server-less" applications (such as cron jobs, backend scripts, etc.) use a value of `urn:ietf:wg:oauth:2.0:oob`.
state An alphanumeric value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery

cURL Example:

curl -F response_type=code \ -F client_id=9b36d8c0db59eff5038aea7a417d64eg347a75b41aac771816d2ef1b3109cc2f \ -F redirect_uri=urn:ietf:wg:oauth:2.0:oob \ -X POST https://app.procore.com/oauth/authorize

Get Or Refresh an Access Token (/oauth/token)

The Get or Refresh an Access Token endpoint retrieves a new access token or refreshes an existing access token. Certain parameter combinations and values are used depending on which scenario you are handling. This endpoint corresponds to the token endpoint described in section 3.2 of the OAuth 2.0 RFC. Note that client-side (JavaScript) applications are not able to use this endpoint to request access tokens or refresh tokens as it requires using the client_secret parameter which is not feasible with client-side applications. Six request parameters are used with this endpoint as described in the following table.

Parameter Description
grant_type Specifies whether you want to retrieve a new access or refresh an existing access token. Use the value `authorization_code` when getting a new access token. Use `refresh_token` when refreshing an existing access token.
client_id specifies the Client ID value you were issued when you registered your application on the Developer Portal.
client_secret Specifies the Client Secret value you were issued when you registered your application on the Developer Portal.
code Specifies the value of the `authorization_code` retrieved from the `/oauth/authorize` call. This parameter is only required when getting a new access code.
redirect_uri Specifies the URI that the user will be redirected to after they grant authorization to your application. For web applications applications, use a `https://` web address. For "server-less" applications (such as cron jobs, backend scripts, etc.) use a value of `urn:ietf:wg:oauth:2.0:oob`.
refresh_token Specifies the refresh token string. This parameter is only required when refreshing an access token.

cURL Example:

curl -F grant_type=authorization_code \ -F client_id=9b36d8c0db59eff5038aea7a417d64eg347a75b41aac771816d2ef1b3109cc2f \ -F client_secret=d6ea27703957b69939b8104ed1234567e210cd2e79af587744a7eb6e58f5b3d2 \ -F code=fd0847dbb559752d932dd3c1ac34ff98d27b11fe2fea5a864f44740cd7919ad0 \ -F redirect_uri=urn:ietf:wg:oauth:2.0:oob \ -X POST https://app.procore.com/oauth/token

Get Token Info (/oauth/token/info)

The Get Token Info endpoint returns details on a specified access token. The request must contain the access token in the Authorization header in this format:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

cURL Example:

curl -H "Authorization: Bearer 53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c" \ -X GET https://app.procore.com/oauth/token/info

Revoke Token (/oauth/revoke)

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 Revoke Token endpoint revokes authorization of an access token. The request must contain the access token in the Authorization header in the following format.

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. Note that the Revoke Token endpoint revokes both the Access Token and Refresh Token. Three request parameters are used with this endpoint as described in the following table.

Parameter Description
token Specifies the value of the access token you want to revoke.
client_id Specifies the Client ID value you were issued when you registered your application on the Developer Portal.
client_secret Specifies the Client Secret value you were issued when you registered your application on the Developer Portal.

To further understand how the Revoke Token endpoint functions, we recommend becoming familier with how access to Connected Apps is revoked using the Procore Web user interface. See the Revoke Access to Connected Apps article on our Support Site for additional information.

cURL Example:

curl -F token=53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c \ -H "Authorization: Bearer 53cff8f4a549beb1c38704158b0f6608a2382f094b6947ecc35c2eed4146a17c" \ -X POST https://app.procore.com/oauth/revoke