# Kudos widget

> Tenant-defined peer recognition — send and receive kudos with a configurable taxonomy.

Source: https://docs.hatched.live/docs/reference/widgets/kudos

## Mount

```html
<script src="https://cdn.hatched.live/widget.js" data-session-token="SESSION_TOKEN" defer></script>

<div data-hatched-mount="kudos"></div>
```

Sending a kudos is a write, so the Kudos widget must be mounted with a
**session token** issued server-side per user. With a `data-embed-token` the
received/given history still renders, but the composer is disabled.

## Script attributes

| Attribute            | Values                 | Default                           |
| -------------------- | ---------------------- | --------------------------------- |
| `data-session-token` | widget session token   | composer enabled                  |
| `data-embed-token`   | embed token            | read-only history                 |
| `data-theme`         | `light` `dark`         | `light`                           |
| `data-api-base-url`  | API origin + `/api/v1` | `https://api.hatched.live/api/v1` |

## Required scopes

- `read` lists received and given kudos.
- Sending a kudos requires a **session token** minted with the `kudos:send`
  scope; a session token without `kudos:send` is rejected `403`, and embed
  tokens are read-only.

## Plan & capability

- Capability: `kudos` (tenant toggle in Settings → Capabilities).
- Minimum plan: **Free**.
- Two distinct 403s can come back:
  - `403 plan_feature_locked` — the plan does not entitle the capability.
    Details carry `required_plan` and an `upgrade_url`.
  - `403 capability_disabled` — the plan entitles it but an operator turned the
    Settings toggle off for this workspace.

## Endpoints

| Method | Path                    | Purpose                                              |
| ------ | ----------------------- | --------------------------------------------------- |
| `GET`  | `/widget/kudos/types`   | Effective kudo taxonomy for the composer            |
| `POST` | `/widget/kudos`         | Send a kudos (`to_buddy_id`, `kudo_type_key`, `message?`) |
| `GET`  | `/widget/kudos/received`| Recent received kudos (Trophy Shelf)                |
| `GET`  | `/widget/kudos/given`   | Recent given kudos + lifetime count                 |

When the taxonomy is empty the API returns the generic virtual set
(`thanks` / `shoutout` / `support`). Sending is rate-limited by a workspace
daily cap (`429`) and de-duplicated inside a 60s accident-click window.