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.
Prerequisites
identity_adminrole- 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,/moverand/leaverwith an API key that has thewrite:jmlscope. 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:
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:
- Creates the user. Because
start_dateis in the future, the user is created asPRE_HIRE(user_status: "PRE_HIRE",is_pre_hire: true). Sign-in is refused until the start date, and pre-hire users are left out ofGET /api/v1/usersunless you passinclude_pre_hire=true. With no start date, or one that is today or earlier, the user is createdACTIVE. - Links the manager if
manager_emailmatches an existing user (otherwise the manager is left empty). - Queues a joiner identity event for the JML workflow engine and fires a
USER_CREATEDwebhook. - Audits
JML_JOINER_PREHIRED(orJML_JOINER_TRIGGEREDfor an immediate hire), with the API key andrequest_idon 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
ACTIVEorPRE_HIRE, the call returns409 USER_ALREADY_EXISTS— usually an HRIS re-send. - Same request sent twice. The same
idempotency_keywithin 24 hours returns the original result withcached: trueinstead 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
DEPROVISIONEDuser, 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:
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:
- Applications you name for provisioning or review — new accounts are provisioned, and review tickets are raised for applications the operator flags for review.
- 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.
- 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. - 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.
- 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:
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:
- Deprovisions every active application account — connected apps through their connector, disconnected apps through a revocation ticket.
- Sets the user to
DEPROVISIONEDand revokes their outstanding email approve/reject links. - Re-evaluates live sessions with the
hr_leavertrigger — suspended when session enforcement is on, recorded only in shadow mode. - 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.
- 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.
- Certification trigger. If you have an enabled certification trigger rule for leavers, a campaign is created for Jane’s residual access.
- 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:
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_idand 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
- For the API-direct approach to driving JML programmatically, see Reference → API Reference
/api/v1/jml/*endpoints (andGET /api/v1/jml/status/{idempotency_key}to check an event) - For the workflow-designer integration to add custom approval steps, see Build a custom approval workflow
- For investigating a specific lifecycle event via Iris, see Iris query patterns → Forensic queries
© AtmanID · Privacy