Invite teammates and clients

Cactal has two invitation flows: organization membership for your team, and website-scoped editors for clients who should see only their website.

Prerequisites

An API key with admin organization access — see Create an API key
A website, for the website-scoped flow — see the Quickstart

Choose the flow

Flow	Scope	Roles	Typical use
Organization invitation	Every website in the organization	`admin`, `full_editor`, `content_editor`	Your own team.
Website editor invitation	One website	`full` (source and content), `content` (CMS and assets)	An agency’s client, a freelancer on one project.

The owner role is not invitable; ownership moves only through a member-role update performed by the current owner. See Access control for the capability each role carries.

Invite a teammate to the organization

POST /v1/organizations/{organizationId}/invitations emails an invitation. role defaults to full_editor when omitted; invitations expire after 48 hours unless you pass expiresAt.

Invite an admin

curl -X POST 'https://api.cactal.ai/v1/organizations/oG8hJ0kL2mN4pQ6rS7tU9/invitations' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "email": "dana@example.com", "role": "admin" }'

Response

{
  "id": "iV3wX5yZ7aB9cD1eF2gH4",
  "email": "dana@example.com",
  "role": "admin",
  "status": "pending",
  "expiresAt": "2026-07-10T15:04:05.000Z",
  "createdAt": "2026-07-08T15:04:05.000Z",
  "url": "https://app.cactal.ai/accept-invitation?invitationId=iV3wX5yZ7aB9cD1eF2gH4"
}

A pending invitation for the same email returns 409; pass "resend": true to cancel it and issue a fresh one. The response always includes the acceptance url. To deliver the link yourself — for example from an agent — pass "sendEmail": false, which creates the invitation without emailing the recipient.The recipient accepts from the email and becomes a member with the invited role. Adjust roles later with PATCH /v1/organizations/{organizationId}/members/{memberPrincipalId} (body { "role": "..." }); assigning owner requires the current owner.

Invite a client to one website

This is the agency pattern: the client gets access to their website and nothing else. POST /v1/websites/{websiteId}/editors takes an email and a website role — full or content.

Invite a client as a content editor

curl -X POST 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/editors' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "email": "client@acme.com", "role": "content" }'

The response depends on whether the email already has a Cactal account:

Response when the email is new

{
  "status": "pending",
  "invitation": {
    "id": "wE5rT7yU9iO1pA3sD4fG6",
    "email": "client@acme.com",
    "role": "content",
    "status": "pending",
    "expiresAt": "2026-07-10T15:04:05.000Z",
    "createdAt": "2026-07-08T15:04:05.000Z"
  }
}

"status": "pending" — an invitation email was sent; it expires after 48 hours by default.
"status": "granted" — the account exists, so the editor grant was applied immediately; the response includes the grant.
"status": "already_inherited" — that person is already an organization member and inherits access from their organization role.

A content editor manages CMS items and assets on that website. A full editor also edits source code and publishes. Neither can see other websites, organization settings, members, or API keys.After accepting, the client lands directly on the shared website. It appears in their dashboard’s unified Sites list alongside any sites they already have, under a “Shared with you” sidebar group; clients without an organization of their own get the same Sites page with a “Recently opened” group. In the API, GET /v1/websites?scope=shared returns exactly this shared set.

Grant or change access directly

When you already know a person’s principal id — for example from the editors list — set their role without an email round-trip:

Upsert a direct editor grant

curl -X PUT 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/editors/pZ2xC4vB6nM8qW0eR1tY3' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "role": "full" }'

Response

{
  "websiteId": "V1StGXR8_Z5jdHi6B-myT",
  "principalId": "pZ2xC4vB6nM8qW0eR1tY3",
  "role": "full",
  "createdAt": "2026-07-08T15:12:44.000Z"
}

The call is an upsert — repeat it with a different role to change access. Granting to an existing organization member returns 400, because members already inherit website access from their organization role.

Remove access and cancel invitations

Remove a website editor:

Remove an editor

curl -X DELETE 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/editors' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "principalId": "pZ2xC4vB6nM8qW0eR1tY3" }'

Access ends immediately; a missing grant returns 404. The same endpoint cancels a pending website invitation: pass { "invitationId": "..." } instead of principalId. Get that id from GET /v1/websites/{websiteId}/editor-invitations?status=pending. Organization invitations cancel with POST /v1/organizations/invitations/{invitationId}/cancel; list their ids with GET /v1/organizations/{organizationId}/invitations?status=pending. Remove an organization member with DELETE /v1/organizations/{organizationId}/members/{memberPrincipalId}.

Verify who has access

List website editors

curl 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/editors' \
  -H "Authorization: Bearer $CACTAL_API_KEY"

List pending website invitations

curl 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/editor-invitations?status=pending&limit=50' \
  -H "Authorization: Bearer $CACTAL_API_KEY"

List pending organization invitations

curl 'https://api.cactal.ai/v1/organizations/oG8hJ0kL2mN4pQ6rS7tU9/invitations?status=pending&limit=50' \
  -H "Authorization: Bearer $CACTAL_API_KEY"

The editors endpoint and each invitation endpoint return { "items": [...], "nextCursor": "..." | null }. An editor entry looks like { "principalId": "...", "role": "full" | "content", "name": "...", "email": "...", "createdAt": "..." }. Pass nextCursor back as cursor until it is null; use status=all to retrieve accepted and canceled history as well as pending invitations. Organization members remain separate at GET /v1/organizations/{organizationId}/members.

Every grant, invitation, and removal is recorded in the organization’s audit log.

Troubleshooting

Symptom	Cause	Fix
`409` `An active invitation already exists for this email`	A pending organization invitation exists.	Retry with `"resend": true`, or cancel the old one.
`400` `Organization team members already inherit website access from their org role.`	Direct editor grants are for people outside the organization.	Change the member’s organization role instead.
Invitation email never arrives	The invitation expired (48-hour default) or went to the wrong address.	Cancel and re-invite, or re-create with `"sendEmail": false` and share the returned `url` directly.
`403` on invitation endpoints	Your API key’s role lacks member management.	Use a key with `admin` organization access.

Next steps

Manage API keys — the same scoping model, applied to keys and agents
Access control concepts for the full role and capability matrix

Get started

Core concepts

Guides

Build with agents

Platform

Invite teammates and clients

Prerequisites

Choose the flow

Troubleshooting

Next steps

​Prerequisites

​Choose the flow

​Troubleshooting

​Next steps

Prerequisites

Choose the flow

Troubleshooting

Next steps