Invite a member (admin)

POST/auth/invite

Create-or-link a user in the tenant and emit a `nest_auth.user_invited` event carrying a single-use set-password token, so YOUR listener can email the invite link (the token is intentionally NEVER returned in the response — that would leak a working credential). The member sets their password via POST /auth/reset-password { token, newPassword }, then signs in. Guarded by the `users.invite` permission — assign it to your admin roles, or call InviteService.inviteUser() directly from your own guarded controller.

Request body

NestAuthInviteRequestDto

Field	Type	Required	Description
`email`	`string`	optional	Email address to invite Example: `member@acme.test`
`phone`	`string`	optional	Phone number to invite Example: `+15551234567`
`tenantId`	`string`	optional	Tenant to invite the member into (ISOLATED: the same email is a distinct account per tenant). Example: `123e4567-e89b-12d3-a456-426614174000`
`metadata`	`object`	optional	Optional metadata stored on a new user and echoed on the invite event for your email template.

Examples

Example

{
  "email": "member@acme.test",
  "phone": "+15551234567",
  "tenantId": "123e4567-e89b-12d3-a456-426614174000"
}

Responses

201Invitation issued: { message, userId, isNewUser }

400Validation failed (bad input).

ApiErrorResponseDto

Field	Type	Required	Description
`statusCode`	`number`	required	HTTP status code Example: `401`
`error`	`string`	required	HTTP status text / exception name Example: `Unauthorized`
`message`	`string`	required	Human-readable message Example: `Invalid credentials`
`code`	`string`	required	Stable, machine-readable error code — branch on this, not the message Example: `INVALID_CREDENTIALS`

Example response

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid credentials",
  "code": "INVALID_CREDENTIALS"
}

401Missing, invalid, or expired authentication.

ApiErrorResponseDto

Field	Type	Required	Description
`statusCode`	`number`	required	HTTP status code Example: `401`
`error`	`string`	required	HTTP status text / exception name Example: `Unauthorized`
`message`	`string`	required	Human-readable message Example: `Invalid credentials`
`code`	`string`	required	Stable, machine-readable error code — branch on this, not the message Example: `INVALID_CREDENTIALS`

Example response

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid credentials",
  "code": "INVALID_CREDENTIALS"
}

Try it

curl -X POST 'https://api.example.com/auth/invite' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{"email":"member@acme.test","phone":"+15551234567","tenantId":"123e4567-e89b-12d3-a456-426614174000"}'

POST /auth/invite

Invite a member (admin)

Request body

Responses

Try it

On this page