Operator - Invitations

Overview

Workspace invitations carry an email, initial role, inviter, expiration, and acceptance state. The list intentionally returns only pending, unexpired invitations; accepted or expired records do not remain actionable there.

Invitation scope is explicit

The workspace_id path must equal the session's selected workspace. A different workspace returns 404 even when the same user belongs to it; switch workspaces first instead of editing the URL.

Resend refreshes, revoke removes

Resending a still-pending invitation refreshes its seven-day expiry and sends the email again. Revocation deletes the outstanding invitation; neither action changes an already accepted membership.

How it works

1. Check for pending work

   List invitations for the selected workspace and search by normalized email. Creating an invite for an existing active member is rejected, so check Members before assuming delivery failed.

2. Close the lifecycle

   Resend only a pending, unexpired invitation; create a fresh invitation after expiry. Revoke mistaken invites promptly, and manage accepted users through the membership API.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

const workspaceId = window.prompt("Current workspace UUID");
if (!workspaceId) throw new Error("A workspace UUID is required");
const response = await fetch(`/api/v1/operator/workspaces/${encodeURIComponent(workspaceId)}/invitations`, {
  credentials: "same-origin",
  headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);

Troubleshooting

The workspace path returns 404

The path workspace must be the session's current workspace, not merely another workspace visible in /operator/me. Switch through the application first.

Resend fails

Only pending, unexpired invitations can be resent. Accepted invitations are membership records; expired ones require a new invitation.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

{
  "invitations": [
    {
      "accepted_at": null,
      "accepted_by": null,
      "email": "invitee@acme.com",
      "expires_at": "2026-04-03T10:00:00Z",
      "id": "7b8c9d0e-1234-4abc-9def-0123456789ab",
      "inserted_at": "2026-03-27T10:00:00Z",
      "invited_by": {
        "email": "admin@acme.com",
        "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
      },
      "role": "member",
      "updated_at": "2026-03-27T10:00:00Z",
      "workspace": {
        "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
        "name": "Acme Corp"
      }
    }
  ]
}

{
  "accepted_at": null,
  "accepted_by": null,
  "email": "invitee@acme.com",
  "expires_at": "2026-04-03T10:00:00Z",
  "id": "7b8c9d0e-1234-4abc-9def-0123456789ab",
  "inserted_at": "2026-03-27T10:00:00Z",
  "invited_by": {
    "email": "admin@acme.com",
    "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
  },
  "role": "member",
  "updated_at": "2026-03-27T10:00:00Z",
  "workspace": {
    "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
    "name": "Acme Corp"
  }
}

{
  "accepted_at": null,
  "accepted_by": null,
  "email": "invitee@acme.com",
  "expires_at": "2026-04-03T10:00:00Z",
  "id": "7b8c9d0e-1234-4abc-9def-0123456789ab",
  "inserted_at": "2026-03-27T10:00:00Z",
  "invited_by": {
    "email": "admin@acme.com",
    "id": "0f1cdac9-305d-4d11-a53d-3fca310c0635"
  },
  "role": "member",
  "updated_at": "2026-03-27T10:00:00Z",
  "workspace": {
    "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
    "name": "Acme Corp"
  }
}