# Key Management

Track physical keys throughout their lifecycle — from creation to archival.

## Key lifecycle

```
ACTIVE → RENDERED → ARCHIVED
              │
              ├──► LOST → REPLACED
              ├──► STOLEN → REPLACED
              └──► DAMAGED → REPLACED
```

Keys are associated with an estate and track who holds them, when they were handed over, and their current condition.

## Create a key

```bash
curl -X POST https://api.faireplace.com/api/places/{place_id}/estates/{estate_id}/keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Cle porte entree",
    "key_type": "CLEF",
    "quantity": 3,
    "description": "3 copies of front door key"
  }'
```

```json
{
  "id": "aabb1122-3344-5566-7788-99aabbccddee",
  "estate_id": "3c4d5e6f-7890-abcd-ef12-34567890abcd",
  "label": "Cle porte entree",
  "key_type": "CLEF",
  "quantity": 3,
  "status": "ACTIVE",
  "created_at": "2026-02-20T10:00:00Z"
}
```

## Key types

| Value | Description |
|-------|-------------|
| `CLEF` | Physical key (door, mailbox, garage, etc.) |
| `CLEF_DUPLIQUEE` | Duplicated key |
| `BADGE_MAGNETIQUE` | Magnetic badge |
| `BADGE_RF` | Radio-frequency badge |
| `BIOMETRIQUE` | Biometric access |
| `TELECOMMANDE` | Remote control (gate, garage) |

## Key statuses

| Status | Description |
|--------|-------------|
| `ACTIVE` | Key registered and available |
| `RENDERED` | Key handed over to the tenant |
| `LOST` | Key reported lost |
| `STOLEN` | Key reported stolen |
| `DAMAGED` | Key reported damaged |
| `REPLACED` | Key has been replaced by a new one |
| `ARCHIVED` | Key no longer in use |

## Status actions

Each status transition has a dedicated endpoint:

| Action | Endpoint | Description |
|--------|----------|-------------|
| Render | `POST .../keys/{key_id}/render` | Hand key over to tenant |
| Return | `POST .../keys/{key_id}/return` | Tenant returns key |
| Lost | `POST .../keys/{key_id}/lost` | Report key as lost |
| Found | `POST .../keys/{key_id}/found` | Mark lost key as found |
| Stolen | `POST .../keys/{key_id}/stolen` | Report key as stolen |
| Damaged | `POST .../keys/{key_id}/damaged` | Report key as damaged |
| Replaced | `POST .../keys/{key_id}/replaced` | Mark key as replaced |
| Archive | `POST .../keys/{key_id}/archive` | Archive key |

## List keys for an estate

```bash
curl https://api.faireplace.com/api/places/{place_id}/estates/{estate_id}/keys \
  -H "Authorization: Bearer $API_KEY"
```

```json
[
  {
    "id": "aabb1122-3344-5566-7788-99aabbccddee",
    "label": "Cle porte entree",
    "key_type": "CLEF",
    "quantity": 3,
    "status": "RENDERED"
  },
  {
    "id": "ccdd3344-5566-7788-99aa-bbccddeeff00",
    "label": "Badge parking",
    "key_type": "BADGE_RF",
    "quantity": 1,
    "status": "RENDERED"
  }
]
```

## Keys in the lease document

Keys are automatically included in the generated lease PDF. The key inventory appears in the entry/exit inspection section (etat des lieux).

When generating a lease PDF, all keys with status `RENDERED` for the estate are listed with their type, quantity, and handover date.

---

## Related

- **[Property Overview](/properties/overview)** — Property hierarchy
- **[Estates API](/properties/estates)** — Manage rental units
- **[Lease Workflow](/signatures/lease-workflow)** — End-to-end lease creation