Documentation
User & admin guide
Back to Calendar
Admin guide

Sign in with herbe ID

Let staff sign in with herbe ID, link members, turn the old email login off, and see what ends when herbe ID ends access.

Configure at Admin → Config → herbe ID sign-in. If herbe ID is not set up on your deployment, the section only says so and offers nothing else.

What it is

herbe ID says who the person is. What they can do in herbe.calendar does not change: roles and account membership stay in herbe.calendar, and you manage them under Members as before.

Set it up

  1. Ask the herbe ID operator for a client for this account.
  2. Give them the two addresses shown in the section: the Redirect URI and the Sign-out return URI. They must be registered exactly as shown. Each has a Copy button.
  3. Enter the Client ID and Client secret you receive, and click Save. The Organisation ID is optional: if you enter it, it is only a check (see step 5). If you have herbe ID's "Copy all" text, paste it into Paste from herbe ID instead: it fills the fields, and nothing is saved until you click Save. The secret is never shown again; to replace it, type a new one.
  4. Click Test connection. It reports Discovery, Keys and Client. All three must pass.
  5. Click Turn on. Turning on runs the test again, then sends you to herbe ID to sign in once with this client. That sign-in is how herbe ID tells calendar which organisation the client belongs to: calendar stores the organisation herbe ID names, not the one typed in the field. You come back to this page and it says whether herbe ID sign-in is on. It is only turned on after that sign-in succeeds, and the sign-in itself does not sign you in to calendar again. Only the admin who pressed Turn on can finish it.

Turn on is refused, with a plain message, when:

  • you filled in an Organisation ID and herbe ID says the client belongs to a different one;
  • the organisation is already linked to another calendar account on this deployment (one organisation, one calendar account);
  • the settings were saved while you were signing in (press Turn on again);
  • herbe ID did not let you in with this client, or its answer could not be confirmed.

Changing the Client ID, the Client secret or the Organisation ID later turns herbe ID sign-in off again, and turns the old staff login back on so nobody is locked out. Press Turn on again to confirm the new settings with a new sign-in.

How people sign in

On the login page people type their email and are sent to herbe ID, then come back signed in. An email code sent by herbe ID works inside ERP windows. Passkeys may not work there. While the old login is on, the login page also offers Use an email code instead.

Someone who is already signed in to herbe ID, and last signed in to this account in this browser, does not see the login page at all: it asks herbe ID once, without showing anything, and opens calendar. If that does not work (no herbe ID session, no access, herbe ID slow or unreachable) the normal login page shows, with no error. After Sign out the login page always shows, even if herbe ID is still signed in, and herbe ID is not asked again for 5 minutes. Calendar inside an ERP window or any frame never does this; it shows the login page as before.

Linking

The first time someone signs in with herbe ID, they are linked to their member entry by email address. The email herbe ID sends is the one the person has in your organisation, which can differ from the one they use in another organisation (elvis@burti.lv in one, elvis@flex.bi in another), so the member entry must carry the address they have in yours. The same applies to the first request from an AI assistant. Once linked, the person is recognised by their herbe ID, not by the address. The Members list shows who is Linked and who is Not linked. Unlink removes the link; the person is linked again the next time they sign in with herbe ID. Unlinking does not sign anyone out: herbe ID decides that, not the Members list (see the next section). To end someone's access, end it in herbe ID (disconnect the app on their person page, remove their access to this app, or remove them from the organisation). Removing them from the account's members also stops the web sessions of that account, but it does not end a paired phone.

What ends when herbe ID ends access

herbe ID is the one place that decides whether someone who signed in with it is still signed in. Calendar asks herbe ID, at most every 5 minutes, whether each such sign-in is still good. When herbe ID says no, everything that sign-in produced ends, in one go, and the next request goes to the login page.

herbe ID does not wait for that check: the moment it ends calendar's access for a person it also tells calendar directly (OpenID Connect back-channel logout), at <calendar address>/api/auth/herbe-id/backchannel. Calendar verifies the message with the account's client ID and ends the herbe ID sign-ins of that person in the account, the same way the check does: when herbe ID names the sign-in that ended, only that one (and the phones paired from it); otherwise all of them. There is nothing to configure: herbe ID derives the address from the calendar address it has on record. If that message never arrives (herbe ID cannot reach calendar), the 5-minute check still ends it.

herbe ID says no when the person signs out of herbe ID, uses Sign out everywhere, disconnects calendar on their connections page, or is removed (membership ended, access to the app switched off, person disabled or erased, the client revoked). Allow a few minutes: calendar learns about it on the next check. A calendar or admin page that is already open in a browser asks calendar about once a minute, so once calendar knows, that page goes to the login page within about a minute (offline or a failed check never signs anyone out).

CredentialComes from a herbe ID sign-in?What happens
Web session (browser)Yes, if the person signed in with herbe IDEnds. Email sign-in sessions are not touched.
Paired mobile appYes, if it was paired from a herbe ID sessionEnds, and its push notifications stop. A phone paired from an email session is not touched.
Mobile app opening the web view, and the one-time link it uses to open Google, Outlook or ERP connectYes, they inherit from the phone that made themEnd with it.
Admin API keys (hcal_)No. They belong to the account, not to a personNot touched. Revoke them under Admin → Tokens.
Share links, the embed page and its short token, booking pagesNo. They do not identify a staff memberNot touched.
Email sign-in link or codeNo. It is the old login, see belowNot touched.
Google, Outlook, Calendly and ERP connectionsNo. They are calendar's own access to those services, not a way into calendarNot touched.

Calendar has no MCP or OAuth sessions of its own. A tool that reaches calendar through the herbe ID MCP connection is ended by herbe ID. What an AI assistant can do there, and who may use it, is described in AI assistant.

If herbe ID cannot be reached, nobody is signed out at once: sessions carry on and calendar tries again on later requests. If herbe ID has not answered for 60 minutes, those sessions end. People sign in again once herbe ID is back.

If calendar's own database is unavailable, nobody can be checked: while that lasts, every request is answered as "not signed in", email sessions included, and nothing is deleted. Sessions work again when the database does. A web session is only refused during such an outage, but a paired phone whose check keeps failing for over 60 minutes is revoked and has to be paired again.

Signing in on two browsers or tabs with the same herbe ID browser session gives two sign-ins in calendar that share one connection at herbe ID. Signing out of one therefore also ends the other, at its next check (within 5 minutes).

A herbe ID sign-in lasts as long as herbe ID allows it (14 days at the time of writing), whatever the 30-day session cookie says. After that, people sign in again.

Sign out in calendar also signs out of herbe ID's connection to calendar. It ends that person's paired phones too, because they came from the same sign-in.

Sessions and paired phones that were created before this feature existed carry no link to herbe ID, so they end on first use and the person signs in again once.

Rotating or revoking the client secret at herbe ID signs everyone out. The check runs with the account's client; when herbe ID refuses that client, every herbe ID sign-in of the account ends within minutes. After rotating the secret, save the new one here (Admin → Config → herbe ID sign-in) straight away, before people's next check.

Turning herbe ID off for the account stops these checks. Existing herbe ID sessions and paired phones of that account are then no longer ended by herbe ID: they carry on until they expire (sessions after 30 days, phones after 90 days without use). To end them, remove the people's access in herbe ID before turning it off, or remove them as members.

Push notifications follow the same rule: a phone paired through herbe ID gets none once herbe ID has ended that sign-in.

Turn off the old staff login

Once every member is linked, Turn off the old staff login becomes available. After you confirm, people can sign in only with herbe ID. Mobile apps that were paired with an email sign-in must be paired again. The change is reversible: Turn the old login back on.

Turning herbe ID off (Turn off) also turns the old staff login back on, so people can sign in with an email code again. It also stops herbe ID from ending existing sessions of the account. If you turn herbe ID on later, the old login stays on until you turn it off again, which checks that every member is linked.

Confirm it's you

While herbe ID is on, these changes ask you to sign in with herbe ID again first (if your last herbe ID sign-in is older than 5 minutes): saving a new client ID, secret or organisation ID (which also turns herbe ID off until you confirm it again with Turn on); turning herbe ID off; turning the old staff login off or back on; unlinking a member. Super admins can turn herbe ID off or turn the old login back on without it (see If herbe ID is down). Test connection and Turn on never ask (Turn on is its own sign-in with herbe ID).

You are sent to herbe ID and brought back to this page; repeat the change afterwards.

If herbe ID is down

A super admin can still get in: super admins can always sign in with an email code. Open the account's Connections page and either turn the old login back on, or turn herbe ID off. No herbe ID sign-in is needed for those two actions. Every other change in this section still asks you to confirm with herbe ID.

Good to know

  • Signing in to a second herbe ID account replaces the first one on that browser session: you can only be signed in with herbe ID for one account at a time.
  • Starting sign-in in two tabs at once makes the first one fail. Start again from one tab.