> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # Zammad > Connect hosted or self-hosted Zammad to Oleria with a personal access token to discover staff users, groups, roles, personal access tokens, OAuth applications, and audit log activity. Zammad is an open-source help desk, hosted at `https://.zammad.com` or self-hosted. Connect Zammad to Oleria to see every staff user in your help desk, the groups and roles that grant their access, and the personal access tokens and OAuth applications that can act on the instance. Oleria connects with a Zammad personal access token, and each integration covers one Zammad instance. ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your Zammad instance: * **Accounts** - every staff user: agents, admins, and any user whose roles grant more than the customer permissions. Each account shows the user's name, email address, login, department, and whether the user is active. A user is marked as an administrator when any of their active roles grants an `admin` permission, and each account shows whether the user is an **Administrator**, an **Agent**, or **Limited staff**, along with the names of their Zammad roles. Each account also shows: * Whether the user can create API tokens. * Their MFA requirement. MFA is required when one of the user's roles is in Zammad's two-factor enforcement list and at least one two-factor method is turned on. * Their sign-in methods: password (unless the password sign-in form is hidden while a third-party login is on), a linked third-party login, and the two-factor methods they enrolled (authenticator app or security key). * Whether SSO is configured for the instance. * Their last activity, which is the later of their last sign-in and their newest web session. * Their last password change, from the audit log. * Whether their password sign-in is locked after too many failed attempts. On hosted Zammad, users with the `ticket.agent` permission are shown with a paid license and other staff with a free one. * **Non-human identities**: * Personal access tokens of every staff user who can create them, each linked to the user it belongs to and acts as. Each token shows its permissions, or full access when no permission is ticked, and its creation, expiry, and last-used dates. Each one is paired with a credential that shows whether the token is active, expired, or disabled. A token is disabled when its user is deactivated or token access is turned off for the instance. * OAuth applications registered in Zammad. * **Groups** - every group and the users with direct access to it, with each user's access levels (**read**, **create**, **change**, **overview**, or **full**). A group's parent appears in its details. * **Roles** - every role, its permissions, and the users who hold it. The built-in **Admin**, **Agent**, and **Customer** roles are marked as standard, and the rest as custom. Group access that a role grants to all its holders appears as access from the role to the group. * **Activity** - events from the Zammad audit log on Zammad 7.2 or later, with the client IP address. This includes created, deleted, deactivated, and reactivated users, password changes, role and group access changes, two-factor enrollment changes, admins viewing Zammad as another user, role permission changes, and changes to SSO, two-factor, password, and other settings. Changes to groups, roles, and other configuration objects are included too. Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model). > [!NOTE] > > Oleria doesn't import customers (your help desk's end users), organizations, tickets, or knowledge base content. This integration covers identity and access governance for staff users, groups, and roles only, so Oleria doesn't populate Access Inventory or resource-level Access Graph data for Zammad. ## Prerequisites * A Zammad instance, hosted or self-hosted, that Oleria can reach over public HTTPS. Activity and last password change dates need Zammad 7.2 or later, and two-factor enrollment needs Zammad 7.1 or later. Earlier versions sync without them. * A Zammad admin who can create roles and users and turn on token access. * Admin access to the Oleria workspace. > [!NOTE] > > Use a dedicated integration user rather than an employee's account, so the integration keeps working if that employee leaves or changes roles. ## Set up a personal access token in Zammad **1. Give the integration user a role** In Zammad, go to **Admin** -> **Manage** -> **Roles** and create a role for Oleria, or choose an existing one, with the permissions in the table below. Then go to **Admin** -> **Manage** -> **Users**, select or create the user Oleria connects as, and give it that role. | Permission | Required | What Oleria uses it for | | :- | :- | :- | | `admin.user` | Required | Every user, each user's personal access tokens and two-factor enrollment, and the user actions. Without it, Zammad lists only the token's own user, so Oleria refuses the token rather than sync a partial inventory. | | `admin.group` | Required | Groups, and the **Create group** action. | | `admin.role` | Required | Roles, and which users are staff and administrators. | | `user_preferences.access_token` | Required | Personal access tokens. Oleria doesn't check it when you authenticate. Without it, Oleria inventories no personal access tokens. | | `admin.security` | Optional | MFA and SSO settings. Without it, MFA and SSO show as unavailable. | | `admin.api` | Optional | OAuth applications, and deleting them. Without it, Oleria reports **Disable non-human identity** as missing a permission, although deleting personal access tokens needs only `admin.user`. | | `admin.session` | Optional | Web sessions, for last activity, and the **Revoke user sessions** action. | | `admin.audit_log` | Optional | Activity and last password change dates. Needs Zammad 7.2 or later. | | `admin.branding` | Optional | Names the integration after the organization name set in Zammad. | Without an optional permission, Oleria skips that data and reports the matching actions as missing permissions. Everything else still syncs. > [!WARNING] > > `admin.user` lets the token change, deactivate, and delete any user, and `admin.role` lets it change which roles grant what. Treat the token as an admin credential. **2. Turn on token access** Go to **Admin** -> **System** -> **API** and make sure **API Token Access** is on. When it's off, no personal access token works. **3. Create the personal access token** Sign in to Zammad as the integration user, select your avatar, then open **Profile** -> **Token Access**, and create a token. Tick each permission from the table above that you granted. A token with no permissions ticked gets every permission of its user. A token can only use permissions its user's roles also grant. Copy the token. Zammad shows it only once. If you set an expiry date, update the token in Oleria before it expires. **4. Let Oleria reach your Zammad instance** Hosted `https://.zammad.com` instances need nothing more. If a firewall protects a self-hosted instance, allow Oleria's egress IP addresses. Contact [support@oleria.com](mailto:support@oleria.com) for the current list. Instances reachable only from a private network aren't supported. ## Connect Zammad to Oleria **1. Open the integration** Go to your Oleria workspace, select **Integrations**, then select the **Zammad** tile. **2. Complete the connection form** | Field | Notes | | :- | :- | | Zammad URL | Required. The HTTPS address of your instance without a path, such as `https://acme.zammad.com` for hosted Zammad or your self-hosted address. A self-hosted address can include a port. You can't change it after you connect. | | Personal access token | Required. The token you created. | **3. Authenticate** Select **Authenticate**. Oleria checks that the token works, that it lists every user rather than only its own, and that it can read groups and roles, then saves the integration. If **Authenticate** fails, the most common causes are: * **API Token Access** is off under **Admin** -> **System** -> **API**. * The token or its user lacks `admin.user`, `admin.group`, or `admin.role`. Grant the permission to the user's role and tick it on the token. * The URL includes a path, or the instance isn't reachable from Oleria over public HTTPS. ## Verify the integration Confirm Zammad appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review the discovered staff users, groups, roles, and non-human identities in your Oleria workspace. The integration's **Capabilities** tab shows **Read users**, **Read groups**, and **Read roles** with the Zammad permissions each one needs, and checks them against your token. > [!NOTE] > > If you replace the personal access token, update it in Oleria by editing the integration. Leave **Personal access token** empty to keep the stored token. To connect another Zammad instance, add a new integration. ## Remediation actions Oleria can take these actions in Zammad. Before an action runs, Oleria checks that the integration user's roles grant the permissions it needs, and reports any that are missing. Every action also reads roles, which needs `admin.role`. If the user or group is already in the requested state, nothing changes. If Zammad accepts a change but Oleria can't confirm it, the action fails with a message saying so. Check the user or group in Zammad before you run the action again, and revert the failed run rather than a later one. Oleria never undoes someone else's change: if the target changed after the action ran, Oleria skips the revert or asks you to finish it in Zammad, and the revert result says which. | Action | What it does | Revert | Zammad permissions | | :- | :- | :- | :- | | Disable user account | Deactivates the user. They can't sign in, and their personal access tokens stop working. Zammad keeps their groups and roles. | Reactivates the user. Skipped if the user is no longer deactivated. | `admin.user` | | Enable user account | Reactivates the user, and unlocks their password sign-in if too many failed attempts locked it. | Deactivates the user again if the action reactivated them. Skipped if the user is no longer active. An unlock isn't undone. | `admin.user` | | Add user to group | Gives the user **full** access to the group. The user must be active and hold a role with `ticket.agent`. If the user already has any access to the group, nothing changes. | Removes the access. Skipped if the user's access to the group changed since. | `admin.user` | | Remove user from group | Removes the user's direct access to the group. The user must be active. If one of the user's roles also grants the group, that access stays, and Oleria reports the roles. | Restores the access levels the user had. Skipped if the user has access to the group again. | `admin.user` | | Add user to role / Remove user from role | Adds or removes one of the user's roles. Inactive roles can't be added, and Oleria won't remove a user's last role. | Reverses the change. Skipped if the role changed since. | `admin.user`, `admin.role` | | Create user | Creates a user with Zammad's built-in **Agent** role and no group access. The user is inactive unless you ask Oleria to activate them. Oleria sets no password, and the user sets one through Zammad's password reset. You can't choose groups or a password in the action. Add groups with **Add user to group** once the user is active. If the **Agent** role is missing, inactive, grants admin permissions, or no longer grants `ticket.agent`, the action fails without creating the user. | Deletes the user. If the user has signed in, or their roles, group access, linked third-party logins, active state, login, or email changed since, Oleria doesn't delete them and the revert fails: deactivate or delete the user in Zammad. | `admin.user`, `admin.role` | | Delete user | Deletes the user. Zammad refuses to delete a user with history, such as tickets or articles, so the action mostly succeeds for unused accounts. Deactivate other users instead. Oleria never starts a Zammad data privacy task, which would also delete the user's tickets. | Not supported. Zammad deletes the user permanently. | `admin.user` | | Create group | Creates a group with the name you enter. If a group with that name already exists, nothing changes. | Deletes the group. Skipped if the group changed after it was created. | `admin.group` | | Revoke user sessions | Ends the user's web sessions, including sessions where the user was viewing Zammad as another user, and sessions where an admin was viewing Zammad as the user. Zammad lists only its newest 10,000 sessions. When the list is full, Oleria ends the user's listed sessions and the action fails, because older ones may remain. Deactivate the user to end them all. Personal access tokens aren't sessions. Use **Disable non-human identity** for them. | Not supported. | `admin.session` | | Disable non-human identity | Deletes a personal access token or an OAuth application, because neither has a disabled state in Zammad. Deleting an OAuth application also revokes every token issued to it. | Not supported. Zammad deletes it permanently. | `admin.user` for personal access tokens, `admin.api` for OAuth applications | Oleria won't act on the user it connects as or on Zammad's system user, and won't delete any personal access token of the user it connects as. Customers aren't imported, so actions don't apply to them. Zammad itself refuses to deactivate or demote the last user with admin permissions. > [!NOTE] > > If the integration user's roles grant a permission but the token doesn't have it ticked, Zammad refuses the change and the action fails with a missing-permission error. Tick the permission on the token, or create a new token and update it in Oleria. ## Known limitations * **No sign-in activity.** Zammad has no API for sign-ins, sign-outs, failed sign-ins, or token use. Oleria takes last activity from each user's last sign-in and newest web session, so a user who only uses a personal access token may look dormant. * **Activity needs Zammad 7.2 or later.** Earlier versions have no audit log API, so Oleria collects no activity or last password change dates. Last password change dates are available only for changes in the last 12 months, the audit log's retention. * **SSO is instance-wide.** Zammad can't require SSO for a user, so Oleria shows SSO as configured or not configured for every user, never as required. If you hide the password sign-in form while a third-party login is on, Oleria stops listing password as a sign-in method. * **Deactivated users show no group access.** Zammad hides an inactive user's group access, so Oleria shows none, and refuses group actions on deactivated users. Reactivate the user first. * **No nested group access.** Zammad groups can have a parent, but grant nothing through it, so Oleria doesn't show access through nesting. * **OAuth applications have no owner.** Zammad doesn't record who created an OAuth application or who uses it. * **Customers aren't imported.** Users whose roles grant only customer permissions aren't shown. A customer who can create personal access tokens is imported as staff. * **No path-based installs.** Oleria connects to the root of the instance. A self-hosted Zammad served under a path isn't supported. * **Paced requests.** Oleria limits its requests to about 10 a second, to avoid slowing down your help desk. * **One instance per integration.** Add one integration for each Zammad instance. ## Contact us For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.