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.

Request

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.

201 response

{
  "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.