Invites

An invite is an offer to join your organization with a role. It never creates a person: the invitee accepts it themselves, by email.

All three routes need an owner who is currently an organization Admin; a Member's token gets 403 insufficient_scope.

Invitations can be sent from the portal (Settings → Team → Invite Member) or with POST /invites below; this API also lists and revokes the pending ones.

The invite object

The invitation token itself is never returned.

{
  "id": "e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b",
  "email": "[email protected]",
  "role": "member",
  "project_ids": ["5b3e9a41-0c7d-4e2f-8a16-9d4b7c2e1f08"],
  "status": "pending",
  "expires_at": "2026-10-01T10:15:00Z",
  "created_at": "2026-09-24T10:15:00Z"
}

Create an invite

POST /api/v1/mgmt/invites

Creates an invitation for email. It runs the same flow as the portal: the address is normalized, role is member (default) or admin (never superadmin), and project_ids grants a member project access on acceptance (every id must be a project of your organization; ignored for admin). An organization with an active SSO connection only accepts the admin's own email domain. No interactive re-login or acceptance step is added here — the invitee accepts by email. Requires Idempotency-Key.

The response carries a status, and its HTTP status code reflects whether a new invite was actually created:

curl -X POST https://portal.<domain>/api/v1/mgmt/invites \
  -H "Authorization: Bearer $TF_PAT" \
  -H "Idempotency-Key: 2a3b4c5d-6e7f-4a8b-9c9d-0e1f2a3b4c5d" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","role":"member","project_ids":["5b3e9a41-0c7d-4e2f-8a16-9d4b7c2e1f08"]}'

s.post(f"{BASE}/invites",
       headers={"Idempotency-Key": str(uuid.uuid4())},
       json={"email": "[email protected]", "role": "member",
             "project_ids": ["5b3e9a41-0c7d-4e2f-8a16-9d4b7c2e1f08"]},
       timeout=30).raise_for_status()

{
  "status": "created",
  "id": "e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b",
  "email": "[email protected]",
  "role": "member",
  "project_ids": ["5b3e9a41-0c7d-4e2f-8a16-9d4b7c2e1f08"],
  "expires_at": "2026-10-01T10:15:00Z"
}

List invites

GET /api/v1/mgmt/invites

The organization's pending invites, newest first. Paginated with limit and cursor; there are no filters.

curl https://portal.<domain>/api/v1/mgmt/invites \
  -H "Authorization: Bearer $TF_PAT"

import os
import uuid
import requests

BASE = "https://portal.<domain>/api/v1/mgmt"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['TF_PAT']}"

pending = s.get(f"{BASE}/invites", timeout=30).json()["data"]
for invite in pending:
    print(invite["email"], invite["role"], invite["expires_at"])

{
  "data": [
    {
      "id": "e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b",
      "email": "[email protected]",
      "role": "member",
      "project_ids": ["5b3e9a41-0c7d-4e2f-8a16-9d4b7c2e1f08"],
      "status": "pending",
      "expires_at": "2026-10-01T10:15:00Z",
      "created_at": "2026-09-24T10:15:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Revoke an invite

DELETE /api/v1/mgmt/invites/{id}

Immediate: the link stops working and the invite leaves the pending list. No body. Requires Idempotency-Key. Returns 204 No Content.

curl -X DELETE https://portal.<domain>/api/v1/mgmt/invites/e2f3a4b5-c6d7-4e8f-9a0b-1c2d3e4f5a6b \
  -H "Authorization: Bearer $TF_PAT" \
  -H "Idempotency-Key: 2a3b4c5d-6e7f-4a8b-9c9d-0e1f2a3b4c5d"

s.delete(f"{BASE}/invites/{invite_id}",
         headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30).raise_for_status()

Errors specific to invites