# Revoke a Guest Badge

`POST /guest.badge.revoke`

## Description

Revoke Guest Badge(s) for an email.

If only one host in the workspace has granted this email, `hostUserId` may
be omitted. If several hosts have, pass `hostUserId` to pick which grant
to revoke (`400` `missing_parameter` otherwise). Same-host alias rows are
all revoked together.

Returns `{ "revoked": true }` when a matching grant was found and deleted,
or `{ "revoked": false }` when there was nothing to revoke (already gone,
including after the host was archived — archiving a member deletes the
badges they granted). Naming an archived host does not 404.

Personal tokens can only revoke badges they issued. Naming another host is
`403` `access_mode_not_supported`; omitting `hostUserId` when only another
host granted the email is a no-op (`revoked: false`).

**Access:** Organization and Personal.

**Required scope:** `guest:write`. Personal Access Tokens use the
`pat:guests:write` group.

See [Guest Badges](/docs/guides/guest-badges).

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `email` | string | Yes | Guest email. ASCII only. |
| `hostUserId` | string | No | Host member. UUID or member email. Required when more than one host has granted this email. Optional for a unique grant, and for personal tokens (defaults to the token owner).  |

## Responses

### 200 - Revoke attempted. `revoked` is true only when a matching grant was deleted.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `revoked` | boolean | Yes | Whether a matching grant was deleted. |

### 400 - Error response. `ok` is always false; branch on the machine-readable `error` code. See the Responses and Errors guide.

### 401 - Error response. `ok` is always false; branch on the machine-readable `error` code. See the Responses and Errors guide.

### 403 - `missing_scope` or `access_mode_not_supported` (personal token named
another host).


### 404 - Named host not found (`user_not_found`).

### 405 - Error response. `ok` is always false; branch on the machine-readable `error` code. See the Responses and Errors guide.

### 500 - Error response. `ok` is always false; branch on the machine-readable `error` code. See the Responses and Errors guide.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/guest-badge-revoke*