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

# Groove.hq

## After this article

You'll be able to connect Groove.hq to Lumos to sync users, roles, groups, and mailboxes, and to provision that access from Lumos: create users, change roles, manage group and mailbox membership, and archive or reactivate users during offboarding.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | User account records. Lumos can create, archive, and reactivate agents |
| Groups | Permission | Yes | Yes | Groups. Lumos adds and removes group members |
| Roles | Permission | Yes | Yes | Roles (Owner, Admin, Agent, Lite User). Lumos can change an agent's role |
| Mailbox | Permission | Yes | Yes | Mailboxes. Lumos adds and removes mailbox access |

| Deprovisioning Action | Type | Description |
| - | - | - |
| Deactivate | User | Archives the agent, which blocks access to Groove.hq. The account Owner can't be deactivated |

Deleting a user isn't supported by the GrooveHQ API. Archiving (Deactivate) is the supported offboarding action.

**Provisioning behavior:**

* **Create:** Lumos first looks up the agent by email. If one already exists, Lumos links that account instead of creating a duplicate. New agents are created with exactly one Role (required) and any number of Mailboxes. Groups can't be included at create time. The new user gets an email invitation to join, so the account shows **Pending** until they accept.
* **Assign or remove a role:** Lumos updates the agent's role directly. Every agent must have a role, so removing a role resets the user to the default **Agent** role.
* **Assign or remove a group or mailbox:** Lumos reads the current member list and writes it back with the user added or removed.
* **Reactivate:** clears the archived flag on the agent.
* **Deactivate:** sets the archived flag. Lumos refuses to deactivate the account **Owner**.

## Required plan and roles

* **Groove.hq role:** the user who generates the API token must be an **Owner** or **Admin**.
* **Connection fields:** Lumos needs an **API token** and your **account subdomain**.
* **Permission scoping:** this integration supports read and write. Lumos syncs users, roles, groups, and mailboxes, and can create users, change roles, manage group and mailbox membership, and archive or reactivate users. Deleting a user isn't supported by the GrooveHQ API, so archiving is the offboarding action.

## Read-only access vs provisioning

**Is read-only possible?** No. Groove.hq connects with a single Global API token tied to an Owner or Admin account, and that token inherently carries read and write access. No narrower, read-only token type is documented.

**What full provisioning requires.** The Global API token generated by an Owner or Admin under Settings → More → Webhooks & API, along with your account subdomain. Follow the steps below.

**Watch out for.** Because there's only one token type, anyone who can generate it can also provision and deprovision users, groups, roles, and mailboxes. There's no way to hand out a lesser-privileged credential for this connector.

## Instructions

**Phase 1: Gather your API token in Groove.hq**

1. Log in to your [Groove.hq account](https://app.groovehq.com/) as an Owner or Admin.
2. Open **Settings** from your profile.
3. Go to the **More** tab and select **Webhooks & API**.
4. Copy the generated **Global token** (the API token).

**Phase 2: Find your account subdomain**

1. Look at your Groove.hq URL. The subdomain is the part before `.groovehq.com`, without the `http`/`https` protocol or the TLD.
2. For example, if your full URL is `https://lumos.groovehq.com/`, the subdomain is `lumos`.

**Phase 3: Connect in Lumos**

1. Find the Groove.hq card in your Lumos integrations (reconnect an existing card or add a new one).
2. Enter the **API token** and the **account subdomain**.
3. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection fails when you enter your credentials.** Confirm the user who generated the API token is an Owner or Admin. Lower-privileged users can't create the Global token Lumos needs.

**The subdomain isn't accepted.** Enter only the subdomain, not the whole URL. Drop the `https://` protocol and the `.groovehq.com` part. For `https://lumos.groovehq.com/`, enter `lumos`.