# List Guest Badges

`GET /guest.badge.list`

## Description

List issued Guest Badges.

Organization tokens return every issued badge in the workspace. Personal
tokens return only badges the token owner issued. This is the issued
(host) view — the same rows `guest.badge.create` returns — not the
guest's hidden-inbox view.

Filter with `email` (alias-aware) and/or `hostUserId` (UUID or member
email). Paginate with `limit` / `cursor` (default 50, max 100). Results
are sorted by `(hostUserId, email)`.

Organization keys that only have `guest:write` must also request
`guest:read` to call list. Personal Access Tokens with `pat:guests:write`
already include `guest:read`.

**Access:** Organization and Personal.
Personal tokens naming a different host return `403`
`access_mode_not_supported`.

**Required scope:** `guest:read`. 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
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `email` | query | string | No | Guest email. ASCII only. Matches the stored address and its verified domain aliases.  |
| `hostUserId` | query | string | No | Host member. UUID or member email — the same convention as [`group.create`](/docs/api/group-create) `members[].userId`. Archived hosts may be named (they typically have no remaining grants). Personal  |
| `limit` | query | integer | No | Number of badges to return per page (default 50, max 100). |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - Issued Guest Badges for this page.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `guestBadges` | GuestBadge[] | Yes |  |
| `nextCursor` | string | No | Opaque cursor for the next page. Omitted when there are no more results. |

**GuestBadge** (array item):

| 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
{
  "guestBadges": [
    {
      "email": "alex@client.example",
      "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "hostUserId": "3f1c0b2a-8d4e-4c91-9a7b-2e6f1d8c0a11",
      "visitPermission": true,
      "acknowledged": false
    }
  ]
}
```

### 400 - `invalid_parameter` (bad `email` / `limit`) or `invalid_cursor`.


### 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-list*