---
title: Revoke an access grant
description: "Revoke an access grant: its token stops working at once. Idempotent, and never blocked by a past-due subscription, so access can always be cut off."
canonical: "https://www.tracepass.eu/docs/revoke-access-grant"
locale: en
source: "https://www.tracepass.eu/docs/revoke-access-grant"
---

# Revoke an access grant

> Revoke an access grant: its token stops working at once. Idempotent, and never blocked by a past-due subscription, so access can always be cut off.

```http
DELETE /api/v1/access-grants/{id}
```

Revoke a grant: its token stops working at once. Idempotent: revoking a grant that is already revoked answers `200` with it again. Only an id that is not your company's answers `404`. An authority grant (an authority role or the authority tier) can only be revoked in the dashboard: through the API it answers `400 role_dashboard_only`.

Revocation is not blocked by a past-due subscription, so a company can always cut access off. It counts as one v1 write when it revokes. The revocation is written to the grant's access log with the API key or app that made it. Honours `Idempotency-Key`.

**Who may call it.** An API key only when its owner switched on "May manage access grants" for that key on the Developer page (off by default; otherwise `403 access_grants_not_enabled`). An OAuth token needs the `access_grants:write` scope and a user who is an admin or owner.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `Bearer <token>` — either a `tp_` API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list. |
| `Idempotency-Key` | header | string | no | UUID v4. |
| `id` | path | string (24 hex chars) | yes | Access grant ID. |

## Examples

```bash
curl -sS -X DELETE https://app.tracepass.eu/api/v1/access-grants/6650c1d2e3f4a5b6c7d8e9f0 \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx"
```

```typescript
await fetch(`https://app.tracepass.eu/api/v1/access-grants/${grantId}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}` },
});
```

```python
import os, requests
res = requests.delete(
    f"https://app.tracepass.eu/api/v1/access-grants/{grant_id}",
    headers={"Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}"},
)
res.raise_for_status()
```

## Responses

### 200 — Revoked

```json
{
  "data": {
    "id": "6650c1d2e3f4a5b6c7d8e9f0",
    "accessLevel": "restricted",
    "label": "Buyer GmbH, order 4711",
    "role": "purchaser",
    "scope": { "kind": "passports", "ids": ["6650a1b2c3d4e5f6a7b8c9d0"] },
    "purpose": null,
    "evidence": null,
    "state": "revoked",
    "expiresAt": null,
    "useCount": 0,
    "createdAt": "2026-06-01T09:30:00.000Z"
  }
}
```

### 403 — Switch off

```json
{
  "error": "access_grants_not_enabled",
  "message": "This API key may not manage access grants. Its owner can switch on 'May manage access grants' for the key on the Developer page."
}
```

### 404 — Not found

```json
{ "error": "Access grant not found" }
```

## Related

- [List access grants](https://www.tracepass.eu/docs/list-access-grants.md)
- [Create an access grant](https://www.tracepass.eu/docs/create-access-grant.md)
