> ## Documentation Index
> Fetch the complete documentation index at: https://docs.accessowl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Revoke an access revocation
> Marks a (pending) access revocation as revoked, recording the caller as the provisioner. When there is no current access left to revoke, the revocation is closed as rejected instead — the returned `status` reflects the outcome.
## Closing revocations provisioned outside AccessOwl
This endpoint is the API equivalent of **Mark as removed**. It marks a pending access
revocation as revoked and records the caller as the provisioner — the programmatic
equivalent of an admin marking the deprovisioning as done. For an application with no
provisioning integration it only closes the record in AccessOwl and never touches the
application itself, which is exactly the case where access was removed elsewhere.
For an application with a provisioning integration, AccessOwl starts deprovisioning as
soon as the revocation is created, so there is no manual task to close and this endpoint
is not what triggers the integration.
This is the revocation-side counterpart to
[granting an access request](/api-reference/access-requests/grant).
If there is no current access left to revoke, the revocation is closed as **rejected**
instead of revoked — there is nothing left to remove. Either way you get a `200`
response; read the `status` field to see the actual outcome (`revoked` or `rejected`).
The other responses are `422` if the revocation was already revoked or rejected, `404`
for an unknown id, `400` for a malformed id, and `403` if the token lacks write
permission.
`provisioning_type` on the returned revocation is surfaced as `automatic` for operations
AccessOwl runs itself. The other value, `application_admin`, marks a manual admin task.
To be notified when a revocation is closed, subscribe to the `revocation.revoked` and
`revocation.rejected`
[webhook events](/guides/webhooks/revocation-events). They fire when the revocation
reaches its final status, whichever outcome it lands on.
## OpenAPI
````yaml POST /api/v1/access_revocations/{access_revocation_id}/revoke
openapi: 3.0.0
info:
description: REST API for AccessOwl third-party integrations
title: AccessOwl API
version: 1.0.0
servers:
- url: https://api.accessowl.com
variables: {}
security:
- bearer: []
tags: []
paths:
/api/v1/access_revocations/{access_revocation_id}/revoke:
post:
tags:
- access_revocations
summary: Mark an access revocation as revoked
description: >-
Marks a (pending) access revocation as revoked, recording the caller as
the provisioner. When there is no current access left to revoke, the
revocation is closed as rejected instead — the returned `status`
reflects the outcome.
operationId: AccessOwlApi.AccessRevocationController.revoke
parameters:
- description: >-
Optional key (1–255 chars) for safely retrying a request. Reusing
the same key for the same request returns `409 Conflict` and is not
processed again — this confirms the request was already received.
Keys are retained for 14 days.
in: header
name: Idempotency-Key
required: false
schema:
maxLength: 255
minLength: 1
type: string
- description: Access revocation ID
in: path
name: access_revocation_id
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AccessRevocation'
description: Access revocation revoked
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Validation error
callbacks: {}
components:
schemas:
AccessRevocation:
description: An access revocation
properties:
application_id:
description: Application ID
format: uuid
type: string
grantee_user_id:
description: User ID of the grantee
format: uuid
type: string
id:
description: Access revocation ID
format: uuid
type: string
inserted_at:
description: Creation timestamp
format: date-time
type: string
permission_ids:
description: Permission IDs being revoked
items:
format: uuid
type: string
nullable: true
type: array
provisioning_type:
description: Provisioning type
enum:
- application_admin
- automatic
nullable: true
type: string
reason:
description: Revocation reason
type: string
requestor_user_id:
description: User ID of the requestor
format: uuid
type: string
resource_id:
description: Resource ID (null for app-wide revocations)
format: uuid
nullable: true
type: string
status:
description: Current status of the revocation
enum:
- processing_access
- rejected
- revoked
type: string
termination_reason:
description: >-
The provisioner's rejection reason when the revocation was rejected;
null otherwise
nullable: true
type: string
required:
- id
- application_id
- reason
- status
title: AccessRevocation
type: object
BadRequestError:
additionalProperties: false
description: Error response for a malformed or invalid request
example:
error: invalid_params
errors:
- field: application_id
messages:
- is invalid
message: Invalid request parameters
properties:
error:
description: Error code
example: invalid_params
type: string
errors:
description: >-
One entry per rejected parameter. Present when a query or path
parameter fails validation, and omitted for other bad requests.
items:
additionalProperties: false
properties:
field:
description: Name of the rejected parameter
example: application_id
type: string
messages:
description: Reasons the value was rejected
example:
- is invalid
items:
type: string
type: array
required:
- field
- messages
type: object
type: array
message:
description: Human-readable error message
example: Invalid request parameters
type: string
required:
- error
- message
title: BadRequestError
type: object
Error:
description: Standard error response
example:
error: not_found
message: Resource not found
properties:
error:
description: Error code
example: not_found
type: string
errors:
additionalProperties:
items:
type: string
type: array
description: >-
Field-specific validation errors, keyed by field name. Present on
422 responses. A 400 response reports its errors as a list instead —
see the BadRequestError schema.
example:
email:
- has invalid format
first_name:
- can't be blank
type: object
message:
description: Human-readable error message
example: Resource not found
type: string
required:
- error
- message
title: Error
type: object
securitySchemes:
bearer:
description: >-
Bearer token authentication. Pass your AccessOwl API token in the
`Authorization` header as `Bearer `.
scheme: bearer
type: http
````