Skip to main content
View as MarkdownOpen in ChatGPTOpen in Claude

Lucca setup

Lucca connects through the unified HRIS connector. This page covers the Lucca-side configuration you complete first. Once it's done, add the connector in Mesh by following Connect your HR system.

You finish with two values:

ValueWhere it comes from
Tenant URLThe base URL of your Lucca instance
API keySettings → API Keys

Before you start​

You need administrator access to your company's Lucca instance, or a colleague who has it.

Third-party product

These steps reflect Axiad's current understanding of Lucca's configuration. Because Lucca is a third-party product, there may be variations between your experience and what this guide describes, depending on the version in use and recent updates.

If you find a significant difference, or anything that doesn't make sense, let us know through Axiad support.

Step 1 — Find your tenant URL​

Sign in to Lucca and copy the base URL of your instance.

The Lucca instance showing its base URL

Entering the Lucca tenant URL in the connection window

Step 2 — Create an API key​

  1. Select the settings gear at the top right and choose API Keys.

    The Lucca settings menu with API Keys

  2. Select Generate a new API Key.

    The API Keys page with the generate action

  3. Name the key, then add permissions:

    PermissionNeeded
    Consult / create / modify usersRequired
    Consult leavesOptional
    Make absence requestsOptional

    Selecting permissions for the new API key

  4. Enter your email address as the technical contact, set the key's usage to Third-party publisher, and select Generate a new API key.

Step 3 — Check role permissions​

After the key is created, confirm the role attached to it can read the employee records you expect Mesh to see. A key with the right permission but a narrow role still returns a partial population.

Step 4 — Connect in Mesh​

Follow Connect your HR system, choose Lucca in the connection window, and supply the tenant URL and API key.

After connecting​

The connector appears in your connectors list with Health: Initializing while the first collection runs, then moves to Good. Access is read-only: Mesh does not write back to Lucca.

If it doesn't come online, see Troubleshoot HR connectors.

Troubleshooting​

What you seeLikely causeFix
Authentication failsThe key lacks the users permissionRegenerate it with Consult / create / modify users
Only some employees arriveThe role attached to the key sees a subset of the populationWiden the role's scope, then wait for the next collection
The connection cannot reach LuccaThe tenant URL includes a path rather than just the baseUse the base URL of your instance