---
title: "Email a single-use onboarding magic link to a provisioned IdP user"
method: POST
path: "/organizations/{organizationId}/idp-users/{email}/onboarding-link"
tags: ["Organizations"]
---

# Email a single-use onboarding magic link to a provisioned IdP user

`POST /organizations/{organizationId}/idp-users/{email}/onboarding-link`

## Request

- Base URL: `https://api.xfa.tech`
- URL: `https://api.xfa.tech/organizations/{organizationId}/idp-users/{email}/onboarding-link`
- Auth: HTTP bearer

Mints a single-use onboarding-link token for a provisioned IdP user who has no reusable MFA factor yet and EMAILS a magic link to the user's secondary/recovery email, so a brand-new device can bootstrap first-device passwordless IdP onboarding. This is the PREFERRED first-device path; the onboarding-password endpoint is the admin-relayed fallback. The token is never returned in the response — it lives only inside the emailed link (only its digest is stored). Requires an organization administrator (RBAC). Returns 404 when the user is not a provisioned IdP user (no existence leak), 409 when the user already has a reusable MFA factor, and 409 when the organization has no identity-provider application configured or more than one (ambiguous).

## Path parameters

- `organizationId` string, required
- `email` string, required

## Response `200`

Onboarding magic link minted and emailed

- object: Confirmation that a single-use onboarding magic link was minted and emailed. The token is deliberately omitted — it exists only inside the emailed link.
  - `expiresAt` integer, required: Unix epoch seconds after which the emailed onboarding link stops working
  - `sentTo` string, required: Masked hint of the recovery address the link was emailed to (e.g. r***@example.com)

## Other responses

- `403`: Not authorized
- `404`: not_provisioned (IdP user not found) or organization_not_found
- `409`: already_enrolled, idp_connection_required or multiple_idp_connections

---

[API](https://skmtc.dev/xfa/apis/xfa-api.md) · [All operations](https://skmtc.dev/xfa/apis/xfa-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xfa/apis/xfa-api/revisions/1a1be0e8972b?raw)