> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Procore

> Connect your Procore company to Oleria to discover Company Directory users, company permission templates, company and project distribution groups, and installed apps, and to manage users and project group membership from Oleria.

Connect Procore to Oleria to see who has company-level access to your Procore company and what they can do with it. Oleria connects through a custom Procore app with a Developer Managed Service Account, and reads your Company Directory, company permission templates, company and project distribution groups, and installed apps from the Procore API. Oleria can also create, deactivate, and reactivate users, change a user's company permission template, and add or remove users in project distribution groups.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Procore company:

* **Company** - the connected Procore company, named after the company, with its environment, zone, and its password and session settings: login lockout, password reset by email, the password reset interval, and the session timeout.
* **Accounts** - every user in the Company Directory, active and inactive, with their name, email, job title, company, employee ID, creation date, and company permission template. Inactive users appear as disabled accounts. Users who aren't employees of your company, such as subcontractors, owners, and vendors, appear as external users. Each user's last sign-in to Procore is their last activity. Users whose company permission template grants **Admin** on the **Company Directory** tool or the **Company Admin** tool are marked as administrators. Each user's default project permission template appears in their profile details.
* **Roles** - every company permission template, with the access level it grants on each company tool, and the users who hold it. A Procore user holds one company permission template at most. Users with custom company permissions have no template, so no role.
* **Groups** - every company distribution group, and every distribution group of each active project, with their members. Project groups show the project they belong to. Distribution groups are notification lists in Procore and don't grant permissions.
* **Non-human identities (NHIs):**

  | Identity | Shown as |
  | :- | :- |
  | Installed apps | Application, with the app's name, publisher, version, app type, installation date, and the user who installed it |
  | The integration's own service account | Application, marked as Oleria's connection |

  Each installed app, from the Procore App Marketplace or a custom app, appears as one non-human identity. It's enabled while the app is installed. Uninstalled apps stay in Oleria as disabled, with the date they were uninstalled. When the user who installed an app is discovered, they're shown as the app's creator and owner.

Oleria refreshes this data on its [regular sync schedule](https://docs.oleria.com/integrations/overview.md#sync-model).

> [!NOTE]
>
> This integration covers company-level access. Apart from project distribution groups, it doesn't read projects, project directories, or project permission templates, so Oleria doesn't populate resource-level Access Graph or Access Inventory data for Procore.

## Prerequisites

* Access to the [Procore Developer Portal](https://developers.procore.com), to create the custom app.
* A Procore **company administrator**, to install the app in your company from **App Management**.
* Admin access on the Oleria platform to add a new integration.

Each integration connects one Procore company. If you have more than one company, install the app in each and add an integration for each. See [Multi-instance support](https://docs.oleria.com/integrations/overview.md#multi-instance-support).

> [!NOTE]
>
> Oleria connects as the app's **Developer Managed Service Account**. Procore adds this service account to your Company Directory when you install the app, so the integration doesn't depend on any person's account. Procore has no OAuth scopes: what Oleria can read and change is set by the company tool permissions you give the service account in the app's manifest.

### Permissions Oleria needs

Give the service account these company tool permissions:

| Procore permission | Used for |
| :- | :- |
| **Company Directory tool: Read Only** | Active users (**Read users**) and distribution groups (**Read groups**). Oleria can't connect without it. |
| **Company Directory tool: Admin** | Company permission templates and their access levels (**Read roles**), and inactive users |
| **Company Admin tool: Admin ('Manage Apps')** | Installed apps, and the company's password and session settings |
| **Project Directory tool: Read Only** | Project distribution groups (**Read groups**), on each project whose groups Oleria reads |

Inactive users can also be read with the granular permission **Create and Edit Users (Based on Assignable Permissions Templates)** instead of **Company Directory tool: Admin**.

Remediation actions need these permissions:

| Procore permission | Required for actions |
| :- | :- |
| **Company Directory tool: Admin, or Standard with the granular permission 'Create and Edit Users (Based on Assignable Permissions Templates)'** | **Disable user accounts**, **Enable user accounts**, and **Create user** |
| **Company Directory tool: Admin** | **Add user to role** |
| **Project Directory tool: Admin, or Standard with the granular permission 'Create and Edit Distribution Groups'** | **Add user to group** and **Remove user from group**, on the group's project |

We recommend **Company Directory tool: Admin**, **Company Admin tool: Admin**, and **Project Directory tool: Admin**, which cover everything Oleria reads and every action. With **Company Directory tool: Read Only** only, Oleria discovers active users and distribution groups. It skips inactive users, builds roles from the templates users hold without their access levels, marks no user as an administrator, and can't run actions. Without **Company Admin tool: Admin**, Oleria skips installed apps and the password and session settings. Without the **Project Directory tool**, Oleria skips project distribution groups. The sync continues in each case.

> [!NOTE]
>
> The exact location of these settings can change over time. If the steps below don't match what you see, refer to Procore's documentation on [Developer Managed Service Accounts](https://developers.procore.com/documentation/developer-managed-service-accounts).

## Create the Oleria app in Procore

**1. Create a custom app**

Sign in to the Procore Developer Portal, go to **My Apps** -> **Create a New App**, and create a custom app for Oleria.

**2. Add a Data Connector component**

In the app, go to **App Versions** -> **Create Version** -> **Add Components**, and add a **Data Connector Component** with **Service Account Authentication** (Developer Managed Service Account). The Developer Portal doesn't save Service Account Authentication on its own, so add the **User Level Authentication** it requires with it too. Oleria connects only as the service account and doesn't use User Level Authentication.

**3. Set the tool permissions**

In the same component, set the company tool permissions **Directory: Admin** and **Admin: Admin**, and the project tool permission **Directory: Admin**. See [Permissions Oleria needs](#permissions-oleria-needs) for what each one covers and what Oleria skips without it.

**4. Promote the app and copy its credentials**

Select **Save Version**, then **Promote Version** to move it to production. Copy the **Client ID** and **Client Secret** from the app's **Production OAuth Credentials**, and the version key you use to install the app.

**5. Install the app in your company**

In Procore, as a company administrator, go to **Company** -> **Admin** -> **App Management** -> **Install App** -> **Install Custom App**. Enter the app's version key and approve the requested permissions.

**6. Find your company ID**

In Procore, go to **Company** -> **Admin** and copy your company ID: the number after `app.procore.com/` in the page URL.

## Connect Procore to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations** -> select **Procore**.

**2. Complete the connection form**

Fill in the connection form:

| Field | Notes |
| :- | :- |
| Procore environment | Required. The Procore environment your company is on: **Production** (`app.procore.com`, including On-Demand Sandboxes), **Federal** (`app.procoregov.com`), **Monthly sandbox**, or **Developer sandbox**. The default is **Production**. Use the Client ID and Client Secret issued for this environment. |
| Client ID | Required. The Client ID of the custom app, from the Procore Developer Portal. It can't contain spaces. |
| Client secret | Required. The Client Secret of the same app. |
| Company ID | Required. The ID of the Procore company the app is installed in. It must be a positive number. |

**3. Confirm the connection**

Select **Authenticate**. Before it saves anything, Oleria:

* requests a token for the app from the environment you chose;
* checks that the company is one the app is installed in, and that it's active in Procore;
* reads the Company Directory, to confirm the service account has at least **Company Directory tool: Read Only**.

The integration is named after your Procore company. Find it on the **Connected** tab of your Oleria **Integrations** page.

If **Authenticate** fails, the message says what's wrong:

* **Procore rejected the client credentials for the selected environment** - check the environment, the Client ID, and the Client Secret. Credentials work only in the environment they were issued for.
* **The company is not one the app is installed in** - the message lists the companies the app can see. Check the company ID, or install the app in that company from **App Management**.
* **The company is inactive in Procore** - connect an active company.
* **The app's service account cannot read the Company Directory** - give the service account at least **Company Directory tool: Read Only**.
* **The Procore app is not connected to this company** - reconnect the app in **Company** -> **Admin** -> **App Management**.

Oleria requests a new token before each one expires, so you don't need to refresh anything.

## Edit the integration

When you edit the integration, you can change **Client ID** and **Client secret**. **Procore environment** and **Company ID** can't be changed, because they identify the connected company. To connect another company or environment, add a new integration.

Leave **Client secret** blank to keep the stored secret. If you change **Client ID**, enter that app's Client Secret too.

## Verify the integration

Confirm the company appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, review the discovered users, roles, groups, and installed apps in your Oleria workspace.

In the integration's **Capabilities and operation readiness** section, **Read users** and **Read groups** show **Available** when the service account has **Company Directory tool: Read Only**, and **Read roles** shows **Available** when it has **Company Directory tool: Admin**. If one shows **Needs permission**, check the service account's tool permissions in the app's manifest and in **App Management**. Each action's row shows the permission listed in [Permissions Oleria needs](#permissions-oleria-needs).

## Remediation actions

Oleria can take these actions in Procore:

| Action | What it does | Revert |
| :- | :- | :- |
| Disable user accounts | Deactivates the user in the Company Directory. The user can no longer sign in to Procore. | Supported - reactivates the user. Procore restores the user's previous permissions and the project directories they were on. |
| Enable user accounts | Reactivates an inactive user. | Supported - deactivates the user again. |
| Create user | Creates a Company Directory user with the first name, last name, and email you provide. The user is inactive unless the request asks to activate them. Procore sends no invitation, so the user can't sign in until you invite them from the Company Directory. No company permission template is set. | Supported - deactivates the user the action created. Procore has no way to delete a user. |
| Add user to role | Sets the user's company permission template. A user holds one template at most, so the new template replaces the current one. | Supported - restores the user's previous template. |
| Remove user from role | Not supported. The Procore API can't clear a user's company permission template, only replace it. To change a user's template, use **Add user to role**. | Not applicable. |
| Add user to group | Adds the user to a project distribution group. | Supported - removes the user again. |
| Remove user from group | Removes the user from a project distribution group. | Supported - adds the user back. |
| Create group | Not supported. The Procore API can't create company distribution groups, and the action doesn't name the project a project group would belong to. | Not applicable. |
| Delete user | Not supported. Procore has no way to delete a user. Use **Disable user accounts** instead. | Not applicable. |
| Revoke user sessions | Not supported. Procore has no way to end another user's sessions. | Not applicable. |
| Disable NHI accounts | Not supported for installed apps. Procore has no API to uninstall or disable an app. Uninstall apps in **Company** -> **Admin** -> **App Management**. | Not applicable. |

Keep these limits in mind when you use these actions:

* Oleria reads the user before it makes a change. If the user is already in the requested state, or already holds the template, Oleria makes no change, and reverting the action makes no change either.
* After Procore accepts a change, Oleria reads the user again to check it. If that read fails, the action succeeds and is marked unverified, and you can revert it. If the read shows the change isn't there, the action fails: check the user in Procore.
* If Procore doesn't answer a change, or answers with a server error, Oleria reads the user again, up to three times. If the change is there, the action succeeds but is marked unconfirmed, because Oleria can't tell that the change was its own. If it isn't, the action fails and nothing changed.
* Oleria won't revert an unconfirmed action. Check the user in Procore and correct it there.
* **Create user** refuses an email that an active or inactive Company Directory user already has. To restore an inactive user, use **Enable user accounts**. If Procore doesn't answer a create and a user with that email exists when Oleria checks again, the action fails, reports the user's ID, and can't be reverted. Check the user in Procore.
* Reverting **Create user** deactivates the user only if they still have the email the action created them with.
* **Add user to role** accepts only company permission templates. It refuses a user with custom company permissions, because replacing them with a template couldn't be reverted. Reverting restores the previous template only while the user still holds the template the action set. If someone changed it in the meantime, Oleria leaves it as is.
* Oleria refuses to deactivate, reactivate, or change the template of the service account this integration connects as, and refuses to add it to or remove it from a group. If Oleria can't read its own service account to rule it out, it refuses the change.
* Oleria refuses to act on an installed app as if it were a user. Manage installed apps in **App Management**.
* **Add user to group** and **Remove user from group** work only on project distribution groups. The Procore API can't change company distribution groups, so Oleria refuses them.
* **Remove user from group** removes each of the group's entries for the user, matched by user ID or by email, and reverting it adds each of them back.
* Procore replaces a project group's whole member list when it's changed, so Oleria reads the group, sends the list with the user added or removed, and reads the group again. If other members are missing afterwards, Oleria puts the original member list back and the action fails. If the user's change isn't there, the action fails: check the group in Procore.

## Known limitations

* **No activity.** Procore has no audit, sign-in, or directory-change API, so Oleria shows no Procore activity. Each user's last sign-in still appears as their last activity, so dormant accounts can be detected.
* **Company-level access only.** Oleria doesn't read projects, project directories, or project permission templates. It reads project distribution groups only. A user's default project permission template appears in their profile details only.
* **No MFA, SSO, or sign-in method.** Procore doesn't expose multi-factor authentication (MFA), single sign-on (SSO), how a user signs in, or when they last changed their password, so these show as unavailable. SSO is configured only in Procore's Company Admin.
* **Company distribution groups are read-only.** Procore distribution groups have no nesting, owners, or permissions. Only project distribution groups can be changed through the API, so group actions work on project groups only, and Oleria can't create groups.
* **No Delete user, Revoke user sessions, Remove user from role, or Disable NHI accounts.** See [Remediation actions](#remediation-actions).
* **No app credentials.** Procore never returns an app's client secret, so installed apps appear without credentials.
* **Other apps' service accounts appear as users.** Procore adds a service account to the Company Directory for each installed app that uses one. Procore doesn't mark these accounts, so only this integration's own service account appears as a non-human identity. Each installed app also appears as its own non-human identity.
* **Administrators depend on template access levels.** Oleria marks administrators from the access levels of each company permission template. When Procore doesn't name a template's levels, or the service account can't read templates, the template's holders aren't marked as administrators.
* **Group members are matched by user ID or email.** A distribution group member that Oleria can't match to a Company Directory user isn't shown as a member.
* **Missing permissions skip data.** Without **Company Directory tool: Admin**, inactive users aren't discovered, so users deactivated in Procore drop out of Oleria instead of showing as disabled. Without **Company Admin tool: Admin**, installed apps and the password and session settings are skipped. Without the **Project Directory tool** on a project, that project's distribution groups are skipped.
* **One company per integration.** One app credential can be installed in several companies, but each integration reads one company.
* **Not yet validated against a live company.** This integration was built from Procore's API documentation. Contact support if a sync or an action reports a permission or format error.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.