# Zendesk

> Connect Zendesk to LightHouse: an agent's API token, what it reads, where the credential is held, and what is indexed.

The engine reads tickets with their comments, and Help Centre articles, from your Zendesk into a knowledge base.

Content is read in place, in your deployment, in your own account. LightHouse receives ids, hashes and counts only. The records are not transmitted, and LightHouse does not open the credential.

## The way to connect

| Way                                      | What you do                                                                                                                                                            |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Paste an agent’s email and API token** | Make an API token in **Admin Center → Apps and integrations → APIs → Zendesk API**, and paste the agent’s email address and the token (two lines). Name your subdomain |

## Connect in LightHouse

You need the **Client administrator** (`client_admin`) role, signed in as a person, and a deployment whose engine reads this connector ([compatibility reference](/concepts/telemetry-contract/#compatibility-reference)) and keeps credentials in your own store.

1. Go to **Setup and admin → Connectors**, find **Zendesk** (search for it, or filter by its family), and choose **Connect**.
2. Fill in `subdomain` (the `<name>` of `<name>.zendesk.com`) and `objects` (tickets, articles).
3. Under **What agents may do with it**, keep **Read only** unless your agents are to write through approved cards.
4. Paste two lines: the agent’s email address, then the API token. Your browser seals it to your deployment; LightHouse never sees it.
5. Your deployment keeps it and checks it at the provider. The card shows the result.

## Connect in code

```yaml
- id: zendesk-knowledge
  purpose: Read Zendesk into the knowledge base.
  executor: python
  target: aal_engine.ingest.connector:run_card
  overseer: ops-lead@example.com
  budget_usd: 0
  effect: internal
  source:
    kind: zendesk
    objects: [tickets, articles]
    comments: true                    # a ticket's comments and internal notes
    label: internal
    credential_secret: <connection id>
    requires:
      reads: [zendesk:tickets with their comments, and published articles]
      reason: the service agents answer from past tickets and the help centre
```

## Permissions

- Zendesk states no scope for an API token: it acts as its agent. Make it on an agent whose groups are the ones the source should read.
- **Read and write** is recorded as your administrator’s choice, for agents that write through approved cards.
- **The health check**: your deployment asks who the token belongs to; Zendesk answers an anonymous user to a token it did not accept, so a missing id fails the check. The card says Zendesk did not state the permissions.
- **One host**: `https://<subdomain>.zendesk.com`, sealed with the credential.

## Where the credential is held

LightHouse never opens this credential. It is sealed in your browser, or by `lighthouse-ai connect zendesk --credential-stdin`, to your deployment’s own key, and your deployment keeps it in your own secrets store under `lighthouse/connectors/zendesk/<connection id>`. A request that sends it to LightHouse unsealed is refused with `422 sealing_required`. LightHouse keeps the connection’s fingerprint, the access level, the scopes the provider states and when it was checked: never the credential, and never what it reads.

See [Where every credential is held](/connect/#where-every-credential-is-held).

## What is indexed

- **Tickets**, with their comments and internal notes, each marked as which. **Articles** from the Help Centre, as text; drafts are not read.
- **How often, and what is read each time**: on the card’s schedule. Tickets changed after the cursor come from Zendesk’s search export, which an agent may use (the incremental export is for administrators only). The search is indexed a little after a change, so the query starts five minutes before the cursor and anything not newer is dropped. Articles come newest first, stopping at the first that is not newer.
- **Deletions**: every six hours the ids are listed and a deleted ticket or archived article is removed.
- **Rate limits**: requests are paced; a `429` waits as long as Zendesk asks.
- **Never read**: attachments, users’ profiles and other Zendesk products.

## Check it worked

- The source’s run note in your deployment: `written N, unchanged N, quarantined N, removed N`.
- **Agents → Knowledge**: documents from `zendesk`.
- Content is read in place, in your deployment. LightHouse receives ids, hashes and counts only; the records are not transmitted.

## Removing it

On the card, choose **Disconnect**. Your deployment deletes the credential from your store. Delete the token in **Admin Center → Apps and integrations → APIs → Zendesk API**. Documents already written stay in the corpus until you delete them.

Source: https://docs.atlanticagenticlabs.com/connect/zendesk/