Add, Modify, or Delete a Service Account

Background

Services Accounts allow you to support integrations that require the Client Credentials grant flow as defined in the IETF OAuth 2.0 Framework Specification. In this scenario, applications need a way to retrieve an OAuth 2.0 access token outside the context of any specific Procore user. OAuth 2.0 provides the Client Credentials grant type for this purpose. A unique client_id and client_secret is generated when a new Service Account is created. For information on implementing the Client Credentials grant flow in an application, see OAuth 2.0 Using Client Credentials on our Developer Portal.

Things to Consider

• Required User Permission:
  • 'Admin' level permissions on the company's Admin tool.
• Access Considerations:
  • A new service account consists of:
    • client_id. The identifier for the service account.
    • client_secret. The secret is a randomly generated code that will be used by the service account. It is only visible to you at the time the account is created. You may want to note the client_secret and then save it to a secure location should you require it in the future for reference. 
      Important! If for any reason you lose the client_secret, Procore recommends using the steps below to create a new service account. 
    • New service accounts are created with Read-Only permissions by default. To change these permissions, see Configure Service Accounts.
• Important Company Directory Considerations:
  • Once you create a service account, the associated email address must not be changed in the company directory. If you modify the service account email address, the service account will no longer be functional.
  • The service account contact cannot be added to more than one company directory (just the one it was created in), or else it will stop working. 

Add a New Service Account

Use the following steps to add a new Service Account.

1. Navigate to the Company level Admin tool.
2. Under 'Company Settings', click Service Accounts.
3. On the Service Accounts page, click +New.
4. Enter a Name for your new Service Account and click Create. The client_id and client_secret for the Service Account are generated and are available for use in making calls to the Procore API /oauth/token endpoint.
5. Configure Service Account permissions. Because the Service Account has default (read-only) permissions at the company level when it is first created, you must set proper permissions for the Service Account prior to using it to access the Procore API.

    Important

   Bear in mind that although you may be able to generate an OAuth 2.0 access token using a Service Account with default (read-only) permissions, this token will not work for making successful calls to the Procore API. Therefore, you must set proper permissions for the Service Account prior to using it to access the Procore API.

Modify a Service Account

Use the following steps to modify an existing Service Account.

1. Navigate to the Company level Admin tool.
2. Under 'Company Settings', click Service Accounts.
3. On the Service Accounts page, locate the account you want to modify and click Edit.
4. Modify the value in the Name field as needed and click Update. Your updated Service Account is saved.

Delete a Service Account

Use the following steps to delete an existing Service Account.

1. Navigate to the Company level Admin tool.
2. Under 'Company Settings', click Service Accounts.
3. On the Service Accounts page, locate the account you want to delete and click View.
4. Click Delete. You will be prompted for confirmation. Click OK.

Reset the Client Secret for a Service Account

Use the following steps to reset the Client Secret for an existing Service Account.

1. Navigate to the Company level Admin tool.
2. Under 'Company Settings', click Service Accounts.
3. On the Service Accounts page, locate the account you want to reset the Client Secret for and click View.
4. Click Reset Secret.
5. A warning displays with the text "Regenerating the Service Account Secret will reset all permissions and project memberships for the Service Account." Click Continue to proceed.
6. Important! Copy the new Client Secret and save it to a secure location. The newly-generated Client Secret is only visible to you once at the time it is created.