# Delete access policy

Canonical page: https://docs.ovok.com/slim-apis/policy/delete-access-policy

| Method | Path |
| --- | --- |
| `DELETE` | `/v1/slim/policy/:id` |

[Authentication](/authentication) · [Access policies](/access-policies)

Deletes an access policy (role) of your project and detaches it from everyone who holds it.

**Auth:** Bearer token for a practitioner, project admin or System Owner session. The caller's access policy must grant `AccessPolicy:delete` and `ProjectMembership:update` (project admins skip this check).
**Scope:** The policy must belong to the caller's project (from the token).

## Request [#request]

### Path parameters [#path-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | Yes | Access policy id. |

## Behaviour [#behaviour]

- The deleted role appears in [change history](/slim-apis/audit/list-change-history) as an `Access` row with key `roleDeleted`; membership role changes appear as `userRoleChanged` rows. See the [key catalogue](/slim-apis/audit/change-history-keys).

- A policy is not deleted while a holder would be left with no role (no `access` entry, not a project admin): the request answers 409 until they are moved to another role. A membership without a policy is treated as full access. Other holders are detached.
- You cannot delete a policy you hold yourself. The request answers 400.
- You cannot delete a policy held by anyone whose role ranks above yours (a project admin ranks as System Owner), since that takes their role away.
- No policy is protected by its name alone: a policy named `Admin` or `System Owner` that nobody holds can be deleted. One that has holders is covered by the rank check above.
- A policy of another project answers 403, also when it is in your parent or a child project. An id that matches no policy answers 404.
- Detaching the members and deleting the policy commit together. Past 49 membership changes they are written in two steps: the members are detached first, so a failed policy delete can leave them without it. Within the limit, a failure changes nothing.
- A failed detach or delete answers 400, also when the single commit hit a write [`conflict`](/errors/conflict) or a lock held by another write.
- The policy's copies of the same name in direct child projects are then deleted: every child policy with the exact same name. A failed copy delete does not fail the request.
- Returns an empty body.


## Example [#example]

```bash
curl -X DELETE 'https://api.sandbox.ovok.com/v1/slim/policy/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Access policy deleted successfully. No body.

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | You hold the policy yourself, the detach or delete failed (including a write [`conflict`](/errors/conflict) at the commit), or the session carries no project or profile. |
| [`401`](/errors/unauthenticated) | The bearer token is missing or invalid. |
| [`403`](/errors/forbidden) | The session is not a practitioner, admin or System Owner session, its access policy lacks a required interaction, the policy or a membership to detach is not in the caller's project, or a holder's role ranks above the caller. |
| [`404`](/errors/not-found) | No access policy has this id. |
| [`409`](/errors/conflict) | Someone still holds the policy and would be left with no role: move them to another role first. In the two-step path, a membership change that lost a write [`conflict`](/errors/conflict) also answers 409. |
| [`422`](/errors/validation-failed) | `id` is not a UUID. |
| [`500`](/errors/internal-error) | The delete failed unexpectedly, or failed and could not be fully rolled back. |
| [`503`](/errors/service-unavailable) | Your access policy could not be read, or the service is temporarily over capacity. Retry shortly, and honour `Retry-After` when it is present. |
