DocsAPI reference

Invitations

Invite people to the organization by email.

Updated Oct 6, 2026

An invitation is addressed to one email and expires after seven days by default. It carries the role the person receives when they accept; on the hosted edition, it can carry permission_policies instead. Acceptance requires the invited email.

When email delivery is configured, withHuman emails the invitation. When it isn't, the link is returned once, when the invitation is created or resent. Resending replaces the previous link and renews the expiry.

See Membership management for invitations, joining and managing access in the app.

List invitations

GET/api/v1/invitationsSession or API keyRequires membership.invite

Returns the organization's invitations in every status, newest first.

Request

Parameters

Parameter	Type	Description
`limit`	query · integer	How many invitations to return. Defaults to 100.

Response

Response codes

Status	Body	Description
`200`	object	The invitations
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot invite people

Response body200

invitationsarray<Invitation>required

Example

GET /api/v1/invitations

curl -X GET "$WITHHUMAN_URL/api/v1/invitations" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"

200 response

{
  "invitations": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "organization_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "email": "[email protected]",
      "grants": [
        {
          "role": "owner",
          "role_name": "string",
          "scope_kind": "organization",
          "scope_id": "string",
          "permissions": [
            "string"
          ]
        }
      ],
      "invited_by_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "status": "pending",
      "expires_at": "2026-09-08T12:02:11Z",
      "accepted_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "created_at": "2026-09-08T12:02:11Z",
      "updated_at": "2026-09-08T12:02:11Z"
    }
  ]
}

Invite a person

POST/api/v1/invitationsSession cookieRequires membership.invite

Invite a member with a predefined role, or, where the edition offers custom permissions (custom_permissions_enabled in the runtime config), with explicit permission policies. Send exactly one of role and permission_policies. Only an owner may invite an owner, every permission must be held by the inviter at the selected scope or wider, and a role or policy holding a sensitive permission needs a fresh sign-in.

Request

Request body

emailemailrequired

Where to send the invitation. The person must accept with this address.

roleenum

A predefined role. owner is full control and only an owner may grant it; admin manages agents, pipelines, paths, members and teams; reviewer decides the requests routed to them; auditor reads everything without changing anything.

One of owner, admin, reviewer, auditor

permission_policiesarray<PermissionPolicySpec>

Custom permissions instead of a role. Refused with 403 custom_permissions_unavailable where the edition offers predefined roles alone.

Response

Response codes

Status	Body	Description
`201`	InvitationWithURL	The invitation and its link. The link appears only in this response
`400`	ErrorResponse	Neither or both of `role` and `permission_policies` were sent, or the role is unknown
`403`	ErrorResponse	You cannot invite people, a grant exceeds what you hold or needs a fresher sign-in, or custom permissions are not available in this edition (`custom_permissions_unavailable`)
`409`	ErrorResponse	A member or a pending invitation with this email already exists, or the organization is at its seat limit

Response body201

invitationInvitationrequired

An invitation to join the organization.

invite_urluri

The link to send to the person. It contains the invitation's secret token, appears only in this response, and only on a deployment with no email delivery configured.

Example

POST /api/v1/invitations

curl -X POST "$WITHHUMAN_URL/api/v1/invitations" \
  -b "withhuman_session=$WITHHUMAN_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "role": "owner",
  "permission_policies": [
    {
      "scope_kind": "organization",
      "resource_ids": [
        "string"
      ],
      "permissions": [
        "string"
      ]
    }
  ]
}'

201 response

{
  "invitation": {
    "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "organization_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "email": "[email protected]",
    "grants": [
      {
        "role": "owner",
        "role_name": "string",
        "scope_kind": "organization",
        "scope_id": "string",
        "permissions": [
          "string"
        ]
      }
    ],
    "invited_by_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "status": "pending",
    "expires_at": "2026-09-08T12:02:11Z",
    "accepted_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "created_at": "2026-09-08T12:02:11Z",
    "updated_at": "2026-09-08T12:02:11Z"
  },
  "invite_url": "https://example.com/webhooks/withhuman"
}

Resend an invitation

POST/api/v1/invitations/{id}/resendSession cookieRequires membership.invite

Issues a new link for a pending invitation and extends its expiry by seven days. The previous link stops working. The new link appears only in this response.

Request

Parameters

Parameter	Type	Description
`id`required	path · uuid	The invitation's id.

Response

Response codes

Status	Body	Description
`200`	InvitationWithURL	The invitation and its new link. The link appears only in this response
`403`	ErrorResponse	You cannot invite people
`404`	ErrorResponse	No such invitation, or it is no longer pending

Response body200

invitationInvitationrequired

An invitation to join the organization.

invite_urluri

The link to send to the person. It contains the invitation's secret token, appears only in this response, and only on a deployment with no email delivery configured.

Example

POST /api/v1/invitations/{id}/resend

curl -X POST "$WITHHUMAN_URL/api/v1/invitations/{id}/resend" \
  -b "withhuman_session=$WITHHUMAN_SESSION"

200 response

{
  "invitation": {
    "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "organization_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "email": "[email protected]",
    "grants": [
      {
        "role": "owner",
        "role_name": "string",
        "scope_kind": "organization",
        "scope_id": "string",
        "permissions": [
          "string"
        ]
      }
    ],
    "invited_by_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "status": "pending",
    "expires_at": "2026-09-08T12:02:11Z",
    "accepted_membership_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
    "created_at": "2026-09-08T12:02:11Z",
    "updated_at": "2026-09-08T12:02:11Z"
  },
  "invite_url": "https://example.com/webhooks/withhuman"
}

Revoke an invitation

DELETE/api/v1/invitations/{id}Session or API keyRequires membership.invite

Revokes a pending invitation. Its link stops working. A revoked invitation cannot be resent. Invite the person again instead.

Request

Parameters

Parameter	Type	Description
`id`required	path · uuid	The invitation's id.

Response

Response codes

Status	Body	Description
`204`		The invitation is revoked
`403`	ErrorResponse	You cannot invite people
`404`	ErrorResponse	No such invitation, or it is no longer pending

Example

DELETE /api/v1/invitations/{id}

curl -X DELETE "$WITHHUMAN_URL/api/v1/invitations/{id}" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"