# 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](../connect-your-hr-system.md).

You finish with two values:

| Value | Where it comes from |
|---|---|
| **Tenant URL** | The base URL of your Lucca instance |
| **API key** | Settings → API Keys |

## Before you start

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

> **warning**

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](/img/connectors/hr/providers/10698718-bd46f542cd.jpg)

![Entering the Lucca tenant URL in the connection window](/img/connectors/hr/providers/10698718-9e03b0cb32.jpg)

## 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](/img/connectors/hr/providers/10698718-37271afd63.jpg)

2. Select **Generate a new API Key**.

   ![The API Keys page with the generate action](/img/connectors/hr/providers/10698718-d47a3943ea.jpg)

3. Name the key, then add permissions:

   | Permission | Needed |
   |---|---|
   | Consult / create / modify users | **Required** |
   | Consult leaves | Optional |
   | Make absence requests | Optional |

   ![Selecting permissions for the new API key](/img/connectors/hr/providers/10698718-913277f6e9.jpg)

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](../connect-your-hr-system.md), 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](../troubleshoot-hr-connectors.md).

## Troubleshooting

| What you see | Likely cause | Fix |
|---|---|---|
| Authentication fails | The key lacks the users permission | Regenerate it with **Consult / create / modify users** |
| Only some employees arrive | The role attached to the key sees a subset of the population | Widen the role's scope, then re-run the collection |
| The connection cannot reach Lucca | The tenant URL includes a path rather than just the base | Use the base URL of your instance |