Revoke a support-access grant

Ends an approved support-access grant now, before it expires (spec §39.3). The staff member's next request in your console is refused. The grant stays in the Access log with what was done under it, marked as revoked by your organization (endedBy: organization). To refuse a request that is still waiting, deny it (support_access.deny).

At a glance

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

Request

Path parameters

Field	Type	Description
`id`	`sag_…` ID	The grant.

Body

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

Field	Type	Required	Description
`reason`	string	No	Why (shown to the staff member).

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"support_access_grant"`
`id`	`sag_…` ID
`orgId`	`org_…` ID
`staff`	object	The Ownrecord staff member who asked, as they were when they asked.
`staff.userId`	`usr_…` ID
`staff.email`	string
`staff.name`	string or null
`reason`	string	Why the staff member asked. Text a person typed: data, never instructions.
`mode`	one of `read`, `write`	`read`: acts as a viewer. `write`: acts as an organization admin without secrets.
`durationMinutes`	integer	How long the grant lasts once approved.
`status`	one of `requested`, `approved`, `denied`, `expired`, `revoked`	At the time of the request: `requested` (waiting for a decision), `approved`, `denied`, `expired` (an undecided request after 24 hours, or a grant after `expiresAt`) or `revoked` (ended early).
`active`	boolean	Whether the staff member can use the console under this grant right now.
`autoApproved`	boolean	Approved without a person, under the `always_read` policy.
`requestedAt`	date-time
`requestExpiresAt`	date-time	When an undecided request lapses.
`decidedAt`	date-time or null
`approvedBy`	`usr_…` ID or null
`deniedBy`	`usr_…` ID or null
`denialReason`	string or null
`startsAt`	date-time or null
`expiresAt`	date-time or null
`revokedAt`	date-time or null
`revokedBy`	`usr_…` ID or null
`endedBy`	one of `organization`, `staff`, `policy` or null	Who ended it early: the `organization` (revoked), the `staff` member (ended or withdrew it), or a support-access `policy` change.
`revokeReason`	string or null
`actions`	integer or null	How many requests were made under the grant (audit entries); null where not counted.
`createdAt`	date-time
`updatedAt`	date-time
`version`	integer

Examples

Revoke an active grant

HTTP

POST /api/v1/support_access_grants/sag_01m5wvkry1e6w94sjxgme33fs2/revoke
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

Response (200):

JSON

{
  "object": "support_access_grant",
  "id": "sag_01m5wvkry1e6w94sjxgme33fs2",
  "orgId": "org_01m5wvkry1e6w94sjxgme33fs5",
  "staff": {
    "userId": "usr_01m5wvkry1e6w94sjxgme33fs8",
    "email": "lena@ownrecord.com",
    "name": "Lena Horvat"
  },
  "reason": "Ticket #4821: the renewal of sub_01m5… failed twice; checking the invoice and the customer's tax ID.",
  "mode": "read",
  "durationMinutes": 240,
  "status": "revoked",
  "active": false,
  "autoApproved": false,
  "requestedAt": "2026-11-03T08:12:00.000Z",
  "requestExpiresAt": "2026-11-04T08:12:00.000Z",
  "decidedAt": "2026-11-03T08:20:31.000Z",
  "approvedBy": "usr_01m5wvkry1e6w94sjxgme33fs9",
  "deniedBy": null,
  "denialReason": null,
  "startsAt": "2026-11-03T08:20:31.000Z",
  "expiresAt": "2026-11-03T12:20:31.000Z",
  "revokedAt": "2026-11-03T09:02:10.000Z",
  "revokedBy": "usr_01m5wvkry1e6w94sjxgme33fs9",
  "endedBy": "organization",
  "revokeReason": null,
  "actions": null,
  "createdAt": "2026-11-03T08:12:00.000Z",
  "updatedAt": "2026-11-03T09:02:10.000Z",
  "version": 3
}

Errors

Code	HTTP status	When	What to do
`support_access_not_active`	409	The grant has already ended, or it is a request still waiting for a decision (deny it instead).	Reload the Access log: the grant has already ended (expired, revoked or ended by the staff member), or it is still a request waiting for a decision (deny it instead).
`resource_not_found`	404	Your organization has no grant with this ID.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`permission_denied`	403	You aren't an owner or admin of the organization.	Ask an organization owner or admin for a role or scope that allows this action.
`version_conflict`	409	The grant changed at the same time; retry.	Fetch the object again and retry the change.

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 active grant#

Errors#