Skip to content

Onboard a Joiner / Mover / Leaver lifecycle

What you’ll do

You’re Sarah Chen. Your HR system (Workday, Rippling, BambooHR, etc.) is the source-of-truth for “who works here + what role + which department.” But IAM lifecycle events (provisioning baseline access on join, revoking on leave, transferring on role change) currently live in a “weekly sync of who-knows-what.” After this tutorial, every JML event triggers automated provisioning, revocation and an audit trail.

Time investment: ~30 min for the first integration setup + perpetual zero-touch per HR event.

The JML activity view: a joiner provisioned to five applications, a mover whose department change waits for approval, and a leaver whose leftover access is flagged.

Prerequisites

  • identity_admin role
  • An HR feed into AtmanID. Two options:
    • Identity Sources (Identity & Access → Identity Sources) — AtmanID syncs from Workday, Rippling, BambooHR, ADP, SuccessFactors, generic SCIM or a flat file.
    • The JML API — your HRIS (or the middleware in front of it) calls POST /api/v1/jml/joiner, /mover and /leaver with an API key that has the write:jml scope. This tutorial uses the API so every step is visible.
  • Birthright access profiles defined (Identity & Access → Roles → Birthright access), e.g. “every Engineering employee gets GitHub + Slack + 1Password”. AtmanID matches profiles on department, identity type and title.

Joiner: new hire arrives

HR creates Jane Doe (Software Engineer, Engineering) on Tuesday with a start date next week. The HRIS calls the joiner endpoint:

Terminal window
curl -s -X POST "$ATMANID_BASE_URL/api/v1/jml/joiner" \
-H "Authorization: Bearer $ATMANID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "wd-12345-hire",
"email": "jane.doe@example.com",
"first_name": "Jane",
"last_name": "Doe",
"department": "Engineering",
"title": "Software Engineer",
"identity_type": "employee",
"manager_email": "alex.lee@example.com",
"start_date": "2026-05-20",
"hris_system": "workday"
}'

AtmanID answers 202 with status: "QUEUED" and:

  1. Creates the user. Because start_date is in the future, the user is created as PRE_HIRE (user_status: "PRE_HIRE", is_pre_hire: true). Sign-in is refused until the start date, and pre-hire users are left out of GET /api/v1/users unless you pass include_pre_hire=true. With no start date, or one that is today or earlier, the user is created ACTIVE.
  2. Links the manager if manager_email matches an existing user (otherwise the manager is left empty).
  3. Queues a joiner identity event for the JML workflow engine and fires a USER_CREATED webhook.
  4. Audits JML_JOINER_PREHIRED (or JML_JOINER_TRIGGERED for an immediate hire), with the API key and request_id on the row.

On the start date, a daily job (00:00 UTC) flips PRE_HIRE users to ACTIVE and audits USER_ACTIVATED_FROM_PREHIRE. Upcoming hires are listed under Identity & Access → Lifecycle → Pre-hire.

The API call records the event as pending and grants no access by itself; pending joiners, movers and leavers are counted on Identity & Access → Lifecycle (Identity Lifecycle (JML)). The joiner workflow — run from that page with the Joiner button — resolves the matching birthright profiles, grants their entitlements, provisions accounts in connected applications (or opens tickets for disconnected ones), and notifies about the new joiner. When it finishes, the API’s joiner event is completed with the outcome, so GET /api/v1/jml/status/{idempotency_key} reports completed, partial or failed instead of pending.

This is the Joiner happy path. From HRIS event to provisioned access with one operator click: the Joiner run.

Joiner edge cases worth knowing

  • User already exists. If the email is already ACTIVE or PRE_HIRE, the call returns 409 USER_ALREADY_EXISTS — usually an HRIS re-send.
  • Same request sent twice. The same idempotency_key within 24 hours returns the original result with cached: true instead of creating anything.
  • No birthright profile matches. Nothing is granted automatically; the joiner workflow reports that there are no applications to provision. Define a profile for the department, or provision manually.
  • Re-hire. If the email belongs to a DEPROVISIONED user, AtmanID reactivates that user (is_rehire: true) instead of creating a new one. Prior access is not restored — the re-hire gets birthright access only. A re-joiner processed through the workflow also gets a 30-day lifecycle hold that pauses HR sync for that user.

Mover: Jane changes department

A year in, Jane moves from Engineering to Platform and gets a new manager. HRIS calls the mover endpoint:

Terminal window
curl -s -X POST "$ATMANID_BASE_URL/api/v1/jml/mover" \
-H "Authorization: Bearer $ATMANID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "wd-12345-move-1",
"user_email": "jane.doe@example.com",
"new_department": "Platform",
"new_title": "Tech Lead",
"new_manager_email": "priya.singh@example.com",
"hris_system": "workday"
}'

At least one of new_department, new_title or new_manager_email is required. AtmanID updates the user, changes the manager, queues a mover identity event and audits JML_MOVER_TRIGGERED. Access is not touched by the call. When the mover workflow runs (from the Mover button on the Lifecycle page), it measures the transfer from the department and title the HR event recorded — the user record already shows the new ones — completes that event with its outcome, and:

  1. Applications you name for provisioning or review — new accounts are provisioned, and review tickets are raised for applications the operator flags for review.
  2. Department-transfer drift. AtmanID computes the stranded access: entitlements Jane holds because of her old department’s birthright profile that the new department’s profile doesn’t confer. Access she requested and had approved is never in that set.
  3. Low-risk stranded entitlements are revoked automatically (audited ENTITLEMENT_AUTO_REVOKED). Medium, high and critical ones get a revocation ticket in the Revocation Queue (Identity & Access → Provisioning Queues → Revocation) for a human to act on.
  4. Certification trigger. If you have an enabled certification trigger rule for movers (Security & Risk → Access Certifications → Trigger rules), a certification campaign covering Jane’s access is created automatically.
  5. SoD scan of Jane’s resulting access, and a notification about the move.

This is the Mover discipline. Remove only what the old department conferred and the new one doesn’t; leave requested access alone; and send anything above low risk to a person. Engineers don’t lose access they still need, and stale access doesn’t quietly accumulate.

Mover edge cases

  • Manager or title change only. The user is updated; no department drift is computed (NO_DEPARTMENT_CHANGE).
  • New department has no birthright profile. AtmanID refuses to treat that as “revoke everything from the old department” — the drift step emits nothing and says why (NEW_BASELINE_UNKNOWN).
  • Suspiciously large drift. More than 25 stranded entitlements for one person is treated as a profile misconfiguration, not a finding, and nothing is revoked or ticketed.

Leaver: Jane leaves the company

Fast-forward 18 months. Jane resigns. HRIS calls the leaver endpoint:

Terminal window
curl -s -X POST "$ATMANID_BASE_URL/api/v1/jml/leaver" \
-H "Authorization: Bearer $ATMANID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "wd-12345-term",
"user_email": "jane.doe@example.com",
"termination_date": "2027-08-31",
"offboarding_type": "voluntary",
"hris_system": "workday"
}'

offboarding_type is one of voluntary, involuntary, contract_end or retirement. AtmanID sets the user’s termination and expiry dates, queues a leaver identity event, fires a USER_DEPROVISIONED webhook, audits JML_LEAVER_TRIGGERED and answers 202 with scheduled_revocation_at (end of day on the termination date). Sign-in is refused once the expiry date passes. Upcoming departures of contractors are listed under Identity & Access → Lifecycle → Contract ending.

On the termination date, the daily scheduled-leaver job (12:00 UTC) runs the full leaver workflow for Jane, as the system, keeping the termination date HR sent. It is the same workflow as the Leaver button on the Lifecycle page, or Terminate on her Directory page, which you can use to offboard her before that date. Whichever runs first completes the queued leaver event, so GET /api/v1/jml/status/{idempotency_key} reports the outcome. The workflow:

  1. Deprovisions every active application account — connected apps through their connector, disconnected apps through a revocation ticket.
  2. Sets the user to DEPROVISIONED and revokes their outstanding email approve/reject links.
  3. Re-evaluates live sessions with the hr_leaver trigger — suspended when session enforcement is on, recorded only in shadow mode.
  4. Handles what Jane owns:
    • AI agents registered through the API and owned by Jane are deprovisioned — unless the agent has a managing team, in which case it keeps running and its accountable owner is cleared for reassignment.
    • Other non-human identities she owns are flagged orphaned for reassignment.
  5. Exchange Online clean-up (for tenants with the Exchange Online connector): removes inbox forwarding rules and removes her from distribution lists and Microsoft 365 / security groups (classic distribution lists are handed back as a manual PowerShell step). Optional steps, when requested on the leaver: set an out-of-office reply, delegate her calendar, and convert her mailbox to a shared mailbox.
  6. Certification trigger. If you have an enabled certification trigger rule for leavers, a campaign is created for Jane’s residual access.
  7. Notifies about the departure.

The response reports what happened: accounts_deprovisioned, tickets_created, agents_deactivated, agents_reassigned, nhis_orphaned and the per-step Exchange counts. Anything that couldn’t be removed automatically is a ticket in the Revocation Queue, not a silent gap.

Leaver edge cases

  • Already deprovisioned. The leaver call returns 409 USER_ALREADY_DEPROVISIONED.
  • Last tenant owner. Offboarding is refused if it would leave the organisation without a Tenant Owner.
  • Immediate termination. For an involuntary exit you don’t want to wait for, terminate the user from their Directory page: sign-in and live sessions stop and entitlements are revoked immediately, then the full leaver workflow runs.
  • Termination + immediate rehire (e.g., contractor → FT conversion). Process the leaver first; the later joiner call reactivates the same user with birthright access only. No automatic restoration of prior access.
  • Connector unavailable at termination time. The account isn’t removed silently: the failure is reported in the leaver result and the account is handled through a revocation ticket or connector retry.

Verifying the full lifecycle audit trail

For a complete view of one person’s lifecycle, open their profile in the dashboard (Directory → the person → Activity), or list joiner events for the period from the audit API (repeat with JML_MOVER_TRIGGERED and JML_LEAVER_TRIGGERED) and filter to the person in the results. action_type is an exact match:

Terminal window
curl -s "$ATMANID_BASE_URL/api/v1/audit?action_type=JML_JOINER_TRIGGERED&since=2026-01-01T00:00:00Z" \
-H "Authorization: Bearer $ATMANID_API_KEY"

The key needs the read:audit_logs scope. Pre-hires are recorded as JML_JOINER_PREHIRED, so query that action type as well. Together the rows give the lifecycle: joiner → activation → mover → automatic revocations and revocation tickets → leaver → deprovisioning and agent clean-up.

This is the JML compliance evidence layer — auditors testing “was access lifecycle-managed for terminated employees” run this query for any employee + see the complete chain.

What just happened

You converted “weekly HR sync of who-knows-what” into:

  • HRIS-driven lifecycle — joiner, mover and leaver events land through the API (or Identity Sources) as they happen
  • Mover discipline — only access the old department conferred is removed; anything above low risk goes to a person
  • Leaver hygiene — accounts, sessions, owned agents and mailbox rules handled in one workflow, with tickets for anything that needs a human
  • Full forensic chain — every JML event audits with the API key, request_id and HRIS system that sent it

Common pitfalls

  • Skipping birthright profiles. Without them, joiners are created but nothing is provisioned automatically, and mover drift can’t be computed. Define profiles per department + per common role.
  • Ignoring the Revocation Queue. Medium/high/critical mover drift and disconnected-app leaver accounts become tickets. Someone has to work them.
  • Reusing idempotency keys. A key reused within 24 hours returns the earlier result instead of processing the new event. Derive keys from the HR event (employee id + event type + sequence).
  • Not reassigning ownership. Orphaned non-human identities and agents with a cleared owner need a new accountable owner. Check them after each leaver.

Going further

© AtmanID · Privacy