> ## 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.

# Teamwork.com

> Connect your Teamwork.com site to Oleria to continuously discover people, teams, companies, roles, projects with per-person access, and non-human identities.

Connect Teamwork.com to Oleria to gain continuous visibility into who has access to your Teamwork site and what they can do in each project. Oleria reads people, teams, companies, roles, project access, and project activity from the Teamwork Projects API. It maps every person, group, role, project, and non-human identity in one place, so you can find dormant, external, or over-privileged access and act on it directly from Oleria.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Teamwork site:

* **Accounts** - every person on the site: standard users, collaborators, client users, and contacts, plus people who were deleted. Each account includes the person's name, email, title, company, user type, whether they're an administrator or the site owner, two-factor authentication, last login, creation date, invitation state, and job roles. People from client companies appear as external users. Contacts can't sign in and deleted people are gone, so both appear as disabled. Non-human identities appear as their own accounts:
  * **Teamwork Bot** - the service account Teamwork runs forms and automations as, linked to the person who created it.
  * **Webhooks** - each webhook, its event, its status, and its receiver address (domain only).
  * **API keys** - each person who holds an API key, linked to that person. Oleria never reads, stores, or shows an API key value.
* **Teams and companies** - every team and company, and their members. Sub-teams appear as their own teams. Teamwork doesn't list a sub-team's members in the parent team, so Oleria doesn't count them as parent-team members.
* **Roles** - each person's user type, site administrator and site owner status, and site permissions (for example **add projects** or **manage people**), with what each one allows. Project roles appear as roles with their members.
* **Projects and project templates** - every project, including archived projects, and every project template. For each project, Oleria shows who has access, what they can do (for example **project administrator**, **view tasks and milestones**, or **add tasks**), and who owns the project.
* **Activity** - changes to project content, such as tasks, task lists, messages, files, and comments, attributed to the person who made them. When a task is assigned to someone, Oleria links that person too.

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

## Prerequisites

* A Teamwork user that is a **site administrator**. Both connection methods act as this user, and Oleria refuses to connect with a user who isn't an administrator, because such a user sees only part of the site.
* Admin access on the Oleria platform to add a new integration.

> [!NOTE]
>
> Teamwork has no service tokens. Connect with a dedicated Teamwork user that isn't tied to an employee, for example `oleria-integration@yourcompany.com`. Then the integration keeps working if a person leaves, or if their key changes or their access is removed.

### Permissions Oleria needs

Teamwork API keys and OAuth tokens have no scopes. They carry the rights of the user they belong to:

| Teamwork permission | Used for |
| :- | :- |
| **Site administrator** | Reading every person, team, company, project, and project role, and running every remediation action |
| **Site owner** (optional) | Discovering every person's API key. With any other user, Oleria discovers only the connection user's own key when you connect with an API key, and no API keys when you connect with OAuth 2.0. |

With the **OAuth 2.0** method, your Teamwork Developer Portal app needs access to the **Projects** product.

> [!NOTE]
>
> The exact location of these settings can change over time. If the steps below don't match what you see, refer to Teamwork's documentation on [API authentication](https://apidocs.teamwork.com/guides/teamwork/authentication) and the [App Login Flow](https://apidocs.teamwork.com/guides/teamwork/app-login-flow).

## Create the integration user

**1. Invite the integration user**

In Teamwork, select **People**, then select **Invite users**. Enter a name and an email address for the dedicated user, for example `oleria-integration@yourcompany.com`. Keep your own company as the **Client** and **Standard user** as the user type. Then select **Next** and send the invite. Accept the invite from that mailbox and set a password.

![Teamwork Invite users dialog with an example integration user](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/teamwork/step-1-invite-user.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=9e8b4539798c4170ce126ecd1129c771)

**2. Make the user a site administrator**

Open the user's profile from **People**. In the **Permissions** section, turn on **Is this user an administrator?**.

![Teamwork user Permissions section with the Is this user an administrator toggle](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/teamwork/step-2-site-administrator.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=2afa7adf73e054bfdfaea5b400cf3996)

## Connect Teamwork.com to Oleria

Choose one method:

* **API key** - you paste the API key of the dedicated user. This is the quickest setup.
* **OAuth 2.0 (Teamwork Developer Portal app)** - you create an app in the Teamwork Developer Portal and approve it as the dedicated user. Use this method if your policy doesn't allow pasting personal API keys into other products.

**API key**

**1. Copy the API key from Teamwork**

Sign in to Teamwork as the dedicated user. Select your profile picture, select **Edit my details**, and open the **API & Mobile** tab. Select **Show your Token** and copy it.

![Teamwork Edit my details API & Mobile tab with the Show your Token button](https://mintcdn.com/oleria/33eFJshuBSuoJ4_n/images/integrations/teamwork/step-3-api-token.png?fit=max\&auto=format\&n=33eFJshuBSuoJ4_n\&q=85\&s=4a6677d58ceb77317df968f3332c0bff)

> [!WARNING]
>
> Treat the API key like a password. Anyone who has it can act in Teamwork as the user who owns it, and the key doesn't expire.

**2. Find Teamwork.com in Oleria**

Go to your Oleria workspace, select **Integrations**, select the **Available** tab, and search for **Teamwork.com**.

**3. Connect in Oleria**

Select the **Teamwork.com** card and choose **API key** as the **Authentication method**. Enter your **Site URL**, for example `https://yourcompany.teamwork.com` (EU and AU sites end in `.eu.teamwork.com` or `.au.teamwork.com`), and paste the **API key**. If your site uses a custom domain, enter its `teamwork.com` address instead. Select **Connect**. Oleria checks the key against Teamwork, and that the user is a site administrator, before saving the integration.

**OAuth 2.0**

**1. Copy the redirect URI from Oleria**

In your Oleria workspace, select **Integrations**, select the **Available** tab, search for **Teamwork.com**, and select the card. Choose **OAuth 2.0 (Teamwork Developer Portal app)** as the **Authentication method** and copy the redirect URI shown. It ends in `/workspace/integrations/teamwork/connect`.

**2. Create an app in the Teamwork Developer Portal**

Sign in to the [Teamwork Developer Portal](https://developer.teamwork.com) as the dedicated user and create an app. Give it access to the **Projects** product. Add two redirect URIs: the one you copied, and the same address ending in `/workspace/integrations/edit` instead, which Oleria uses when you reconnect. Copy the app's **Client ID** and **Client secret**.

> [!NOTE]
>
> An app that isn't published is available only to the Teamwork account that created it. Create it while signed in as the dedicated user, so that this user can approve it.

**3. Connect in Oleria**

In the Oleria connection form, enter the **Client ID** and **Client secret**, then select **Connect**. Teamwork opens in your browser. Sign in as the dedicated user, choose your site, and approve the app. Oleria connects to the site you choose. The site comes from the approval, so there's no site URL to enter.

## Verify the integration

Confirm the new instance appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review the discovered accounts, teams, companies, roles, projects, and activity in your Oleria workspace.

> [!NOTE]
>
> An integration can't move to a different Teamwork site. To connect another site, add a new integration. If you edit the integration with a key or approval for a different site, Oleria refuses it.

> [!NOTE]
>
> If someone regenerates the dedicated user's API key, or removes the user's administrator rights, the integration shows as unhealthy. Edit the integration in Oleria and enter the new key, or restore the user's rights.

## Remediation actions

Beyond discovery, Oleria can act on Teamwork access to remediate risk. Every remediation action needs the connection user to be a site administrator. Oleria checks this before running any action.

| Action | Reversible? |
| :- | :- |
| Disable user | Yes - Teamwork has no suspend option, so Oleria changes the person to a **Contact**, who can't sign in. The person keeps their projects and history. Reversed by restoring their previous user type and permissions. |
| Enable user | Yes - changes a contact back to a standard user, which takes a paid seat. Reversed by changing them back to a contact. |
| Delete user | No - Teamwork has no API to restore a deleted person. Oleria records the person's email and user type so you can invite them again. |
| Create user | Yes - creates a standard user in your company, and sends the invite if the action asks to activate them. Add the user to teams afterwards with Add user to group. Reversed by deleting the new user. |
| Add user to group (team) | Yes - reversed by removing the user from the team. |
| Remove user from group (team) | Yes - reversed by adding the user back. |
| Create group (team) | Yes - reversed by deleting the team while it has no members. |
| Add or remove a role | Yes - changes a site permission, a project role's members, or the user type (to change a user type, add the person to another user-type role; a user type can't be removed). Site owner and client user can't be changed from Oleria. Reversed by restoring the previous value. |
| Revoke permission (project) | Yes - removes the person from the project. Reversed by adding them back and restoring their project permissions. If a permission doesn't come back as it was, Oleria reports the reversal as partial and lists the permissions to set in Teamwork. |
| Remove access for external accounts | Yes - removes a client user or another person outside your company from a project. Reversed the same way as Revoke permission. |
| Disable NHI (webhook) | Yes - pauses the webhook. Reversed by resuming it. Oleria refuses a webhook whose status it doesn't recognise, rather than report it as disabled. |

A few safeguards apply to every action:

* Oleria won't disable, delete, or change the user type of the user the integration connects as, the site owner, or Teamwork Bot. It also won't change their team or project-role memberships or remove them from a project, won't remove the connection user's administrator or manage-people rights, and won't remove the site owner's site permissions.
* Teamwork Bot is managed by Teamwork, and changing it can break forms and automations, so Oleria also won't change its site permissions.
* Teamwork doesn't allow removing a project's owner from the project, so that action reports a failure and changes nothing.
* Remove access for external accounts refuses people from your own company.
* A reversal only undoes the change Oleria made. If someone changed the same person, team, or project in Teamwork in the meantime, for example by adding a removed person back to a project, Oleria leaves it as is.

## Known limitations

* **Sign-ins and security events aren't available.** Teamwork has no audit log API. Activity in Oleria covers changes to project content.
* **Removing a team member or a project role member replaces the whole list.** Teamwork has no API to remove a single member, so Oleria reads the list and writes it back without that person. A member added in Teamwork at the same moment could be dropped.
* **Single sign-on is a site setting.** Teamwork reports whether SSO is enabled for the whole site (Enterprise plan), not for each person. Last password change isn't available.
* **Other people's API keys need the site owner.** Teamwork lists every API key only to the site owner. With any other connection user, Oleria discovers only that user's own key when you connect with an API key, and no API keys when you connect with OAuth 2.0.
* **Oleria shares your site's API rate limit.** Teamwork allows 150 API requests a minute for the whole site on most plans. While a sync runs, Oleria can use most of it, so other integrations on the same site may be slowed down.
* **API keys and the Teamwork Bot can't be disabled from Oleria.** Teamwork has no API to revoke another person's key or to disable its service account. Disable or delete the key's owner instead.
* **AI Teammates aren't discovered.** Teamwork has no API for them.
* **Tasks, messages, files, and other project content aren't imported.** Oleria reads who can access each project and what they can do, not the content itself.

## 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.