Person invites and sign-in

A Person is a human who can sign in. This page covers how a Person gets credentials from an invite, how they finish profile setup, and how they verify or change their email, verify a phone, and set or reset a password.

Treat every sessionToken and emailed token as a secret and don't log it.

Prerequisites

• To send an invite: an Account credential with scope users.authorization:write, and the id of an existing Person.
• To redeem an invite: the single-use inviteToken from the invitee's email. No credential is needed.
• For the email, phone, and password calls: a signed-in Person session where the path personId is that Person. API keys are rejected with 403.

Endpoints

Person statuses

A Person's status moves Created, Invited, Pending, Active, and can end as Inactive or Disabled.

1. Send the invite

curl -X POST https://api.wingspan.app/v3/platform/persons/$PERSON_ID/invite \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "X-Wingspan-Account: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "expiresIn": "P7D", "message": "Welcome to the team." }'

The body is optional. Fields:

The 200 response is a receipt: id, personId, expiresAt, sentTo, createdAt, and credentialGrant. The invite link is never returned to you. It goes to the invitee by email only. credentialGrant: true means the link lets the invitee set credentials; false means it's an action link for a Person who already has credentials. Re-issuing an invite replaces any unused outstanding invite. Errors: 404 for an unknown Person, 409 for a conflict with the Person's state.

2. The invitee requests a link or redeems the token

POST /v3/platform/persons/initialization-links takes { "email": "..." }. It also accepts the captcha fields captchaToken, captchaVersion, and forceCaptcha. For a credential-less Person it sends a registration link. For an Active Person it sends a reset-password link. Otherwise it does nothing. The response is always 200 for a well-formed request and doesn't reveal which case applied:

{ "success": true, "message": "..." }

Pre-production environments also return magicLink. Errors: 422 for a malformed email, 429 when the rate limit is hit, 503 when the service is unavailable.

POST /v3/platform/persons/invite-redemptions takes { "inviteToken": "..." } and returns 201 with a Person session:

Errors: 404 for an unknown token, 410 when the token is expired or already used, 422 when inviteToken is missing, 503 when redemption is unavailable.

3. Set the first password

Call POST /v3/platform/persons/{personId}/reset-password with the redeemed session and { "newPassword": "..." } and no token. Do it within 30 minutes of redemption; the invite-redemption session is exempt from the usual MFA step-up only during that window.

4. Submit profile setup

After redemption, send the profile with POST /v3/platform/persons/submissions-as-self (Person session) or POST /v3/platform/persons/submissions (invite token as the bearer). Neither takes ids in the body, and neither accepts X-Wingspan-Account.

The 200 response has personId, status, and a requirements summary. Don't send profile, credentials, or requirementFulfilments: the API returns 422. Identity data goes through ComplianceEntity, credentials through the password call above, and requirements through the onboarding surfaces. Other errors: 401 without a bearer, 403 for an API key on submissions-as-self, 410 InviteTokenExpired for an expired invite token on submissions.

Verify email and phone

POST .../verify-email with no body requests a new verification email. With { "token": "..." } it completes verification. It never changes the address. The response is the Person. A request from an API key or another Person returns 403 or 404.

POST .../verify-phone has the same shape for SMS (token optional).

Change the sign-in email

1. POST .../change-email with { "email": "[email protected]" }. Needs a recent MFA step-up for HighRiskWriteAction. The API sends a confirmation link to the new address and returns 204. Errors: 403 for an API key or missing step-up, 404, 409, 422.
2. POST .../confirm-email-change with { "token": "..." }. The API updates the sign-in and displayed email, marks it verified, signs the Person out of every V3 session, and returns the Person. A wrong or used token returns 404.

Sign in again with the new email and password afterwards.

Reset or change a password

POST .../reset-password has three forms:

A password is 8 to 512 characters, has at least one ASCII letter and one digit, and has no whitespace. A successful change revokes every session of that Person.

Webhooks

The catalog lists Person.* events. Subscribe with POST /v3/platform/webhooks. See Webhooks and events.

Related pages

• Team access and roles
• Stakeholder invitations