Skip to main content

​
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

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

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