---
title: "Invite a member to the caller's tenant"
method: POST
path: "/members"
tags: ["Members"]
---

# Invite a member to the caller's tenant

`POST /members`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/members`
- Auth: HTTP bearer

Creates a pending member and its single-use invite link. The response carries `invite_token`; send the invitee a link built from it. The link works for 7 days, after which the member is reported as `expired` until an admin resends or revokes it. The inviter's email is taken from the credential that sends the invite, never from the body. Requires admin or owner (`member:manage`); a caller cannot invite a role above their own, and `owner` is reached only by promoting an existing member.

## Request body

- object
  - `email` string, required
  - `role` 'owner' | 'admin' | 'member' | 'viewer'
  - `inviter_name` string: Display name of the person sending the invite, shown to the invitee. Optional; at most 80 characters.

## Response `201`

Invited

- Member
  - `id` string, required
  - `tenant_id` string, required
  - `email` string, required
  - `role` 'owner' | 'admin' | 'member' | 'viewer', required
  - `status` 'active' | 'pending' | 'expired', required: `active` once accepted, `pending` while the invite link works, `expired` once it has lapsed.
  - `invited_by` string: The accepting user's id in the calling application, when one was supplied at accept.
  - `inviter_email` string: Who sent (or last re-sent) the invite, resolved from the sending credential.
  - `inviter_name` string: The sender's display name, when one was supplied.
  - `invite_sent_at` string, date-time: When the current invite link was issued.
  - `invite_expires_at` string, date-time: When the current invite link stops working. Absent for members never invited by link.
  - `invite_token` string: The single-use invite token. Present only in the invite, resend and get-invite responses, never in the roster.
  - `accepted_at` string, date-time
  - `created_at` string, date-time, required

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)