Logging in to Zammad with an API token

Written by Michał, the developer of Zamio · Updated:

Zamio logs in to Zammad with a personal API token instead of a password. You enter it once and stop thinking about logging in. This page covers what the administrator has to enable and what each agent does.

Why a token and not a password

I chose tokens for security, and because it's the most practical option on a phone:

  • Your password never touches the app. It also works when you log in to Zammad through SSO or use two-factor authentication.
  • Limited permissions. The token gets only ticket.agent, and that's enough for everything the app does.
  • You can revoke it at any time in Zammad without changing your password, for example when you lose your phone.
  • It stays on the device. The token is kept in the iOS Keychain or the Android Keystore. It isn't stored in any cloud. The app connects directly from your phone to your company's Zammad.

For administrators: allow token access

  1. In Zammad, open the admin settings (gear icon) and go to Settings → System → API.
  2. Turn on API Token Access.

If an agent still doesn't see Token Access in their profile, check that their role has the permission user_preferences.access_token (Manage → Roles).

For agents: create a token

  1. In Zammad in the browser, click your initials or avatar in the bottom-left corner and choose Profile → Token Access.
  2. Click Create.
  3. Name: something that tells you where it's used, e.g. Zamio – iPhone.
  4. Permissions: tick ticket.agent.
  5. Expiration date: optional. Without it, the token works until you delete it.
  6. Click Create and copy the token right away. Zammad shows it only once.

Tip: open Zammad in the browser on the phone itself and create the token there. Then you just paste it into the app and don't have to send it to yourself by email or chat.

Log in to Zamio

  1. Server URL: the address you use for Zammad in the browser, for example https://support.example.com, without anything after the domain.
  2. API token: paste the token.

That's it. You stay logged in until you log out, or until the token expires or is deleted.

Lost phone or leaving employee

Delete the token in Zammad under Profile → Token Access. The app loses access to Zammad immediately. The account and password don't change.

Troubleshooting

“Invalid API token”
The token was copied incompletely, has expired or was deleted. You can't view an existing token again, so create a new one and delete the old one.
I don't see “Token Access” in my profile
The administrator hasn't enabled API token access, or your role lacks user_preferences.access_token. See the administrator section above.
The app can't connect to the server
Check the address: https:// at the start, no path after the domain, and the same address you use in the browser. If Zammad is reachable only on the company network or VPN, the phone has to be on that network too.
Tickets or groups are missing
The app sees exactly what your Zammad account sees. If something is missing, check your groups and roles in Zammad.

Once you're logged in, the next step is setting up push notifications.