POST /v1/console/orgs/{org_id}/invites


Call	`POST /v1/console/orgs/{org_id}/invites`
Price	free
Scope	console session cookie (not an API key)
Operation id	`createInvite`

What it does

Invite someone by email with a role. They get a magic link (valid 7 days, single use) that adds them to the organization when they sign in with it. Only an owner may invite an owner; inviting an existing member answers 409. Audited as member_invited (and member_added on acceptance). Roles: owner, admin (checked server-side). When the user has TOTP on, the session must have passed POST /v1/console/totp/verify; an owner of an organization with more than one member must have TOTP on (spec 9.1), otherwise 403.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

curl -X POST 'https://api.askverdict.io/v1/console/orgs/org_01JC3Z4Y8R9K2M5N7P1Q3S5T7V/invites' \
  --cookie "verdict_session=$VERDICT_SESSION" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "role": "developer"
}'

Example response

201: The invitation was sent.

{
  "id": "0b8f6c1e-3d2a-4f5b-9c7d-1e2f3a4b5c6d",
  "email": "[email protected]",
  "role": "developer",
  "invited_by": "usr_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "expires_at": "2026-11-14T14:00:00Z",
  "created_at": "2026-11-07T14:00:00Z"
}

Parameters

Name	In	Type	Required	Description
`org_id`	path	string	yes	The organization.
`idempotency-key`	header	string (uuid)	yes	A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 `idempotency_conflict`.

Request body

Schema CreateInviteRequest. Who to invite.

Field	Type	Required	Description
`email`	string (email)	yes	Who to invite.
`role`	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	Role on accepting. Only an owner may invite an owner.

Response fields (201)

Schema Invite.

Field	Type	Required	Description
`id`	string (uuid)	yes	The invitation id.
`email`	string (email)	yes	Who was invited.
`role`	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The role the invitee gets on accepting.
`invited_by`	string	yes	Who sent the invitation.
`expires_at`	string (date-time)	yes	When the invitation expires.
`created_at`	string (date-time)	yes	When it was sent.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
`400`	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (`invalid_request`).
`401`	Missing, malformed, revoked or expired API key, or a bad webhook signature (`unauthorized`).
`403`	The key lacks the scope this operation needs (`forbidden_scope`).
`404`	The resource does not exist in this organization (`not_found`).
`409`	The `Idempotency-Key` was reused with a different request, or the first request is still running (`idempotency_conflict`).
`429`	Rate limited (`rate_limited`). Wait `Retry-After` seconds.
`500`	Unexpected server error (`internal`). Not billed; retry with the same `Idempotency-Key`.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.