Revoke an invitation · Ownrecord docs

Revokes a pending invitation: its link stops working at once. Accepted, revoked and expired invitations can't be revoked (invitation_not_pending). Give a reason: it goes to the audit log.

Like members, you can only revoke invitations you could have sent (an admin can't revoke an invitation to become an owner). Needs members:admin; a security-tier change.

At a glance

REST: POST /api/v1/invitations/{id}/revoke
MCP tool: invitations_revoke
Operation ID: invitations.revoke
Scope: Organization
Permission: members:admin
Risk tier: security
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the members:admin scope
Since: M1

Request

Path parameters

Field	Type	Description
`id`	`invt_…` ID

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`reason`	string	No

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`invt_…` ID
`object`	`"invitation"`
`orgId`	`org_…` ID
`email`	string
`role`	one of `org_owner`, `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer`
`scope`	object
`status`	one of `pending`, `accepted`, `revoked`, `expired`
`expiresAt`	date-time
`invitedBy`	`usr_…` ID
`acceptedAt`	date-time or null
`revokedAt`	date-time or null
`createdAt`	date-time

Examples

Revoke an invitation sent to the wrong address

HTTP

POST /api/v1/invitations/invt_01m4tx5nj8emwbyf7y9vcf47x8/revoke
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "reason": "Sent to the wrong address"
}

Response (200):

JSON

{
  "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
  "object": "invitation",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "email": "finance@acme.example",
  "role": "finance",
  "scope": {
    "type": "entity",
    "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
  },
  "status": "revoked",
  "expiresAt": "2026-10-20T12:00:00.000Z",
  "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "acceptedAt": null,
  "revokedAt": "2026-10-14T09:30:00.000Z",
  "createdAt": "2026-10-13T12:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`resource_not_found`	404	No such invitation in this organization.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`invitation_not_pending`	409	The invitation was already accepted, revoked or has expired.	This invitation was already accepted, revoked or has expired. Nothing to do.
`role_not_grantable`	403	The invitation grants more access than you have.	Ask an organization owner to grant this role and scope, or pick a role and scope within your own access.
`version_conflict`	409	The invitation changed at the same time (for example, it was accepted).	Fetch the object again and retry the change.
`permission_denied`	403	You can't manage members of this organization.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Revoke an invitation sent to the wrong address#

Errors#