Sync & end-to-end flow

When sync runs

Sync is per-user and runs:

• right after the user submits their token, and
• every time the user’s app starts or comes to the foreground.

There is no server-side scheduled sync and no partner-initiated push. Practical consequence: a change on your side becomes visible in Oase when the affected user next opens the app. For enrolment this is fine — the user opening the app is exactly the moment they need to see their group space — but e.g. removing a user from a group only takes effect in Oase on that user’s next sync.

What happens on each sync

Per user:

1. Change detection. Oase hashes the raw response body and skips all processing when it is unchanged since the last sync. (HTTP ETag headers are not used — a byte-identical body is the cheap “nothing changed” path, so avoid gratuitous nondeterminism such as randomly re-ordering groups.)
2. Profile. Name and photo are applied to the user’s identity in the realm.
3. Enrolment. Each group in groups[] gets its group space created on first sight, named from display, and the user is added to it.
4. Reconciliation. The user is removed from any mirrored group space not backed by a group in the response. The groups[] list is authoritative for that user.

Mirrored group spaces are marked as externally controlled: they cannot be deleted from inside Oase, and their membership is managed by sync.

End-to-end example

Say your platform organises volunteer activities, and when an activity becomes real you want its participants to get a shared space in Oase. One-time setup: Oase creates a realm for your platform and registers you as its identity provider (see Registration); you receive the realm’s join link in return. Then, per activity:

1. You create a group in your own datastore — no API call to Oase — with a stable id (value) and the activity’s name (display), and associate the signed-up users with it, so each of those users’ SCIM records now lists the group.
2. You send the participants the realm join link (mail, SMS, in-app — the same link for everyone; it opens the Oase app, or the app-store page for users who don’t have it yet).
3. Each user opens the link and joins the realm. Because the realm has an identity provider, the app answers 403 {"reason": "requires_authentication", "info": { ... }} with your login details in info — it shows a “log in with your-platform” prompt and runs the login flow.
4. Your login page redirects back with the token; the app stores it with Oase; Oase syncs — the activity’s group space now exists and the user is in it, with their name and photo from your platform.
5. From then on the user’s groups re-sync on every app start. When the activity ends, you remove the group (or its members) on your side, and each member drops out of the mirrored space on their next sync.

Note: the group space for an activity is created lazily by the first member who completes the flow — there is no “create the space now” API call, and no space appears for an activity none of whose members have joined.