# Update a Guest Badge

`POST /guest.badge.update`

## Description

Update `visitPermission` on an existing Guest Badge.

[`guest.badge.create`](/docs/api/guest-badge-create) is idempotent and
does **not** change `visitPermission` on an existing grant. Use this
endpoint to flip on-map visit access after create.

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 update (`400` `missing_parameter` otherwise). Same-host alias
rows are updated together.

Personal tokens can only update badges they issued. Naming another host
is `403` `access_mode_not_supported`; omitting `hostUserId` when the
token owner has no matching grant is `404` `not_found`.

**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).  |
| `visitPermission` | boolean | Yes | Whether the guest may visit the host on the map. |

## Responses

### 200 - The updated Guest Badge.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `email` | string | Yes | The guest's email address (lowercase). |
| `userId` | string | No | The guest's chat address ID, when one has been provisioned. Omitted if the address is not yet available.  |
| `hostUserId` | string | Yes | The host member's user ID (always a UUID, even if you passed an email). |
| `visitPermission` | boolean | Yes | Whether the guest may visit the host on the map. |
| `acknowledged` | boolean | Yes | Whether the guest has acknowledged the badge. |


#### Example Response

```json
{
  "email": "alex@client.example",
  "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "hostUserId": "3f1c0b2a-8d4e-4c91-9a7b-2e6f1d8c0a11",
  "visitPermission": false,
  "acknowledged": false
}
```

### 400 - `missing_parameter` (`visitPermission` omitted, or `hostUserId`
required because several hosts granted this email) or
`invalid_parameter`.


### 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`), or no matching grant
(`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-update*