Add a user to a tenant.

This endpoint assigns a user to a specific tenant. Either user_id or email must be provided. If email is provided, it will be resolved to a user_id before proceeding.

Request Parameters

• tenant_id (UUID): The UUID of the tenant to assign the user to
• user_id (UUID, optional): The UUID of the user to add
• email (str, optional): The email of the user to add; converted to user_id if provided. If no account exists for the email, a stub user is created and added — they join automatically when they sign up with that email.

The new member is always emailed (COG-6177) — a sign-up CTA if they have no account yet, a plain "you were added" notice if they do.

Response

200 — the member is in and the tenant pod knows them (sync_status: "ok"). 207 — the member is in, but the tenant pod does not know them yet: sync_status is "unreachable" (pod cold, suspended or restarting) or "rejected" (the pod answered with an error). Nothing was mailed. POST the same member again once the workspace is up — re-adding an existing member re-runs the push and the notification (already_member: true); it is not a conflict.

Body: message, pending_invite (an account had to be stubbed), invite_email_sent, sync_status, already_member.

Error Codes

• 400 Bad Request: Neither user_id nor email provided
• 403 Forbidden: Caller is neither the owner nor an admin of this tenant
• 404 Not Found: User or tenant doesn't exist
• 503 Service Unavailable: Caller is not the owner, and the workspace could not be reached to confirm they are an admin; nothing was written
• 500 Internal Server Error: Error adding user to tenant