The calendar in Apple Calendar, Outlook and CalDAV

Applies to: SimpleTwo 0.9.x · Checked: 01.10.2026

The platform's calendar is not read only by our own app: a subscribed Outlook refreshes on its own schedule and a CalDAV client polls the server itself. That is why the calendar service sits beside the chat rather than inside it, and why it has a public name.

Three ways to connect a third-party client, from simplest to fullest:

Method	What it gives	Direction	For whom
ICS subscription	the calendar visible in any client that understands webcal://	read-only	Apple Calendar, Outlook, Google Calendar, a meeting-room screen
CalDAV	a whole calendar account: the calendar list, events, free/busy	read (writing as it ships, see below)	Apple Calendar on macOS/iOS, Thunderbird, any CalDAV client
CardDAV — the directory	the corporate directory as an address book	read-only	the same clients, configured separately
CardDAV — your books	personal address books and a team's books, in the same account as CalDAV	read and write	the same clients, the same account

1. An ICS subscription — the shortest path

A subscription is issued for one calendar and carries its secret in the link itself. The secret is shown once: rotating issues a new link and invalidates the old one.

Getting a link:

curl -fsS -X POST "https://dir.<domain>/cal/v1/calendars/<id>/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"My laptop"}'

The response carries two links to the same resource:

{
  "calendar_id": "cal-…",
  "url": "https://dir.<domain>/cal/v1/calendars/cal-…/subscribe.ics?key=…",
  "webcal_url": "webcal://dir.<domain>/cal/v1/calendars/cal-…/subscribe.ics?key=…",
  "note": "shown once — rotating replaces it"
}

The difference is practical: a client downloads the https:// one as a file, while it treats webcal:// as a subscription and keeps it updated. Apple Calendar and Outlook want the second.

The link is the access

It carries no password and no session of yours: whoever has the link sees the calendar. So issue one per device with a clear label — revoking then breaks nothing else — and do not drop it into a shared chat. To revoke: DELETE /v1/credentials/{id}.

Apple Calendar (macOS). File → New Calendar Subscription → paste the webcal://… link → refresh every 15 minutes. Turn the subscription's own alerts off: they duplicate the reminders that already arrive as pushes in SimpleTwo Connect.

Apple Calendar (iOS). Settings → Apps → Calendar → Accounts → Add → Other → Add Subscribed Calendar → paste the link.

Outlook (new and web). Calendar → Add calendar → Subscribe from web → paste the https:// variant.

A meeting-room screen. For a resource calendar the same call also returns a panel address (now_url): the screen on the wall is not a subscriber, it asks "what is here now". One secret opens both the subscription and the panel.

2. CalDAV — an account, not one calendar

CalDAV gives a client everything at once: the calendar list, events, free/busy. Discovery works the standard way, so the client only needs a server name and credentials.

What	Value
Server	dir.<domain>
Discovery	https://dir.<domain>/.well-known/caldav
Root	https://dir.<domain>/dav/
User	your SimpleTwo login
Password	an app password from identity's portal with the scope "calendars (CalDAV)" — see below; a session token or the domain password will not do

Apple Calendar (macOS). Settings → Accounts → add CalDAV → type "Manual" → username, app password, server dir.<domain>.

Which password: identity's app password

Third-party programs sign in over a protocol — mail (JMAP, SMTP), calendars (CalDAV), contacts (CardDAV) — in one way across the platform: an app password the person creates in identity's portal (the "App passwords" card). Each password has its scopes, one per protocol:

Scope in the portal	What it opens
"calendars (CalDAV)", caldav	calendars and invitations in the calendar service
"contacts (CardDAV)", carddav	your address books in the calendar service and the organisation's directory
"reading mail", jmap · "sending mail", smtp	mail

For a phone, where one CalDAV account gives both the calendars and the books, tick both. The password is shown once, is revoked on its own and does not reveal your main password. Wrong attempts count toward the account's lockout exactly like a wrong password on the sign-in page, and every sign-in shows in the portal's "Recent sign-ins". App passwords are turned on by the organisation's administrator in the console, under Security → Sign-in requirements; while they are off, the portal has no card for them.

The calendar's device passwords and the dav_auth switch. CalDAV passwords used to be issued by the calendar service itself (POST /v1/credentials, a "device password"). Moving to app passwords takes two steps, and the order matters:

1. While the administrator's dav_auth switch is at calendar (the default), the calendar service accepts both the old device passwords and identity's app passwords. In this period everyone creates an app password and puts it in their programs instead — nothing breaks, the two work side by side.
2. The administrator moves dav_auth to identity (the coordinator's console, PUT /admin/api/settings/dav-auth with {"mode":"identity"}). From then on the calendar service's CalDAV and CardDAV accept only app passwords from people; a device password is refused with the reason, and no new device password is issued (POST /v1/credentials answers 409). The switch will not go to identity while identity is not deployed or its app passwords are off, and it reminds the administrator that passwords are to be created first. Going back to calendar is always possible — the old device passwords work again.

The old passwords cannot be carried over automatically: the service keeps only their digests. Subscriptions (the ICS links of §1) and meeting-room panels are not a person signing in, and the switch does not touch them.

What a CalDAV account can do (from directory 0.71.0 — the full set Apple Calendar on macOS and iOS expects):

Feature	How it works
Calendars, events, series, exceptions	read and write; sync-collection, calendar-query, calendar-multiget, free-busy-query
Invitations	the server sends them itself (RFC 6638, calendar-auto-schedule): an attendee sees the invitation in the scheduling inbox and in their calendar as "not confirmed"
Accept / decline / tentative	the answer goes to the organiser; the attendee's status changes in the organiser's calendar
Cancelling a meeting	the organiser deletes the event — attendees are notified and see the meeting as cancelled until they acknowledge it; an attendee deleting it leaves the meeting rather than cancelling it
Propose another time	an attendee moves the meeting in their own calendar — the organiser receives a proposal (iTIP COUNTER), the meeting itself does not move; the organiser accepts or declines in a SimpleTwo client
Reminders	alarms (VALARM) are each attendee's own and survive the organiser's edits
Calendar name and colour	set in the calendar's properties in the client (PROPPATCH)
Delegation	calendars shared with you for reading or writing appear in the account and are listed as delegation (calendar-proxy)
Address books	CardDAV in the same account — see §4
Attendee search	the invitees field finds people and rooms in the directory (principal-property-search), with the same visibility as the apps' search (from directory 0.72.0)
External guests	an attendee with an address outside the organisation receives the invitation and the cancellation by mail from the organiser's mailbox — when the organiser has mail (the Mail product); without a mailbox no mail goes out (from directory 0.72.0 and mail 0.89.0)
Unacknowledged cancellations	a cancelled meeting the attendee never opened leaves their calendar on its own after 30 days
Tasks	Apple Reminders lists (VTODO): a list is made from the client; tasks with a date, priority, status and alarms live in the same service (from directory 0.73.0)
Attachments	a file attached to a meeting or a task in the client is kept by the service (25 MB per file, 100 MB per entry) and reachable to every attendee by the link in the entry; the files live in the object store (the s3 role or the organisation's own, bucket simpletwo-calendar), sealed, and without one attachments are off (from directory 0.73.0)

Not there: notes (Apple Notes sync over IMAP, not CalDAV) and push notifications: Apple Calendar takes push from Apple's own servers only, a third-party server cannot offer it, so the client polls at the interval in its own settings (15 minutes by default, one minute at the shortest).

CalDAV is off by default: it is a setting of the organisation, not of one server. An administrator turns it on in the coordinator's console: Settings → the "CalDAV and CardDAV" card → "Turn CalDAV on". Every host of the directory role applies it on its next poll (about a minute) and restarts the service; the state shows in the role's /cal/healthz as caldav.

Why CalDAV rather than "just use our app"

Because half of your colleagues already have their calendar open in another program, and asking them to check their schedule in two places is a reliable way to get a schedule nobody maintains. The server serves what our own client sees, with the same rights.

3. CardDAV — the organisation's address book

Colleagues are found on a phone through the ordinary contact search, dialling included: the same CardDAV account as the personal books (§4) carries the Organisation address book. No separate account is needed.

What	Value
Discovery	https://dir.<domain>/.well-known/carddav
The book	https://dir.<domain>/dav/addressbooks/<login>/_organisation/
User and password	the same as in §4

Who is in it is decided by the address-book policies — the same rule as the search in the SimpleTwo app (Groups — The global address list). A guest whose group limits what they see finds on the phone exactly whom they find in the app. Not in the book: the people one knows only from a conversation (the app finds them by name), switched-off accounts, bots, meeting rooms and the person themselves. An account hidden from the address book is found by its exact address only — it is not in this listing.

The book is read-only: it reflects the directory, and an employee's record is corrected where it is maintained.

4. Personal and shared address books — CardDAV beside the calendars

Since 28.09.2026 a person's address books live in the calendar service — the split Active Directory and Exchange make: the directory (people, groups and the organisation's contacts) stays in the identity service, and what sits "in a person's mailbox" — their books and their team's books — is the calendar's. So one CalDAV account on a phone gives both the calendars and these books: the discovery address and user are those of §2, and the app password needs the scope "contacts (CardDAV)" ticked.

What	Value
Discovery	https://dir.<domain>/.well-known/carddav
Your books	https://dir.<domain>/dav/addressbooks/<login>/
One book	https://dir.<domain>/dav/addressbooks/<owner>/<book-id>/
User and password	your login and identity's app password with the scope "contacts (CardDAV)"; until the dav_auth switch the calendar's device password works too

What to know:

• A book shared with you is listed beside your own, at its owner's address. You can write to it when the owner granted write; otherwise the client shows it read-only.
• identity's app password is you. Your own rights on books and calendars apply. The calendar's old device password is a ceiling: one issued at full reads books and does not write to them — not even your own; writing needs write.
• Books shared with a group are not visible over CardDAV yet: a password names the person, not their groups. The SimpleTwo app shows them.
• A contact points at somebody. A card with no e-mail, no phone and no login (X-SIMPLETWO-USER) is not stored: the server refuses it with valid-address-data. Everything else a phone writes — a photo, several addresses, field labels — is kept as it is and returned to the client unchanged.
• A new book is made in the app, not in a CardDAV client: a book needs a name and an id the server mints.
• Book contents are encrypted on disk with a key the calendar service gets from the coordinator and holds in memory only. The service's /healthz shows books_sealed.

The directory (§3) and the organisation's book stay where they were: they are the directory's objects, not a person's data.

When it does not work

Symptom	Cause
The client downloaded one file and never updates	the https:// link was used instead of webcal://
The subscription is empty	the link's access level shows the calendar without contents, or there really are no entries in the subscribed window
CalDAV will not accept the work password	the domain password does not apply here: use an app password from identity's portal, with your login as the user name
After the dav_auth switch the phone stopped syncing	the old device password is no longer accepted: create an app password in identity's portal and replace the password in the account — see §2
Calendars sync but books do not (or the other way round)	the app password lacks the scope: "calendars (CalDAV)" or "contacts (CardDAV)"
Refused with "the account is locked until …"	too many wrong attempts in a row; the lockout is shared with the portal's sign-in, wait until the time given
An event created in Apple Calendar did not appear in SimpleTwo	CalDAV is switched off in this installation — Settings → "CalDAV and CardDAV", see §2
Apple Calendar offers no Accept/Decline on an invitation	the client never saw calendar-auto-schedule: the account was added before directory 0.71.0 — remove it and add it again
Moved somebody else's meeting in my calendar and it did not move for the others	by design: an attendee moving a meeting proposes another time to the organiser; only the organiser moves it
A link stopped working after rotation	as intended: rotation invalidates the old secret, issue a new subscription
The phone will not save a contact to a book	the card has neither an e-mail nor a phone, or the old device password was issued without write, or the book is shared with you read-only — see §4
A book shared with a group does not show on the phone	as built today: CardDAV lists the books shared with you by name — see §4
The client cannot find the server by name	/.well-known/caldav does not answer: check that dir.<domain> is in DNS and the service has a certificate