# Badges widget

> A shelf of the buddy's earned and locked badges.

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

## Mount

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

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

## Required scopes

- `read`

Badges are included in the shared `/widget/state` snapshot, so the widget stays
in sync with the buddy widget without a second token. The dedicated
`GET /widget/badges` endpoint (earned + locked next-up tiles) is
capability-gated, so the 403s below apply when that endpoint is called.

## Plan & capability

- Capability: `badges` (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.