Team invitation flow

1. Issue an invitation

Call the invitations endpoint with the invitee email and a role. Roles are owner, admin, or member. The response includes a signed accept URL you can email or surface in your own UI. Tokens are single-use and bound to the team and role at creation time.

// POST /v1/teams/:teamId/invitations
{
  "email": "engineer@meridian.dev",
  "role": "member",
  "expiresInHours": 72,
  "metadata": {
    "source": "admin-console",
    "invitedBy": "usr_8B5CF6"
  }
}

// Response 201
{
  "id": "inv_F472B6",
  "status": "pending",
  "acceptUrl": "https://meridian.getnimbus.net/invite/inv_F472B6",
  "expiresAt": "2026-06-30T18:00:00Z"
}

2. Handle acceptance

When the invitee clicks the accept URL, Meridian validates the token, attaches the user to the team with the pre-baked role, and fires a team.member.added webhook. If the invitee does not yet have a Meridian account, the accept page transparently funnels them through signup and resumes the join automatically once verification completes.

• •Idempotent: re-clicking the link is a no-op after acceptance.
• •Audit log captures IP, user agent, and originating invite id.
• •Role downgrades require a fresh invitation, not an edit.

3. Revoke and rotate

Pending invitations can be revoked any time before the recipient accepts. Revocation invalidates the signed URL immediately and emits a team.invitation.revoked event. To rotate access for an already-joined member, remove their membership and issue a new invitation at the desired role — this keeps audit trails crisp and avoids ambiguous role history.