# Partager un coffre

> Ouvrez un coffre à un autre utilisateur, par exemple le patient ou un confrère, consultez les partages et révoquez-les.

Un partage donne à un utilisateur l'accès à un coffre qu'il ne possède pas : il le voit dans sa liste et y fait ce que ses rôles HDS permettent. C'est aussi le moyen d'ouvrir son propre dossier à un patient.

## Avant de commencer

- Le coffre existe. Voir [Gérer les coffres](/v1.0/hds/gerer-les-coffres).
- Vous connaissez l'identifiant Keycloak du destinataire : le `sub` de son jeton, que votre application obtient par `/me` ou à sa connexion.
- Le destinataire porte un rôle HDS adapté, par exemple `HDS_PATIENT` ou `HDS_MEDICAL`. Voir [Attribuer les rôles](/v1.0/hds/attribuer-les-roles).
- Vous êtes propriétaire du coffre et portez le rôle `HDS_HEALTHCARE` ou `HDS_ADMIN`.

## Créer un partage

::::tabs{sync="lang"}
:::tab{label="cURL"}
```bash
curl -X POST "https://api.wakastart.app/api/hds/shares" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vaultId": "vlt_a1B2c3D4",
    "targetUserId": "2c9d7e41-5a8b-4f60-9e3d-1b7a6c5d4e21",
    "level": "READ"
  }'
```
:::
:::tab{label="TypeScript"}
```typescript
export async function shareVault(userToken: string, vaultId: string, recipientSub: string) {
  const response = await fetch("https://api.wakastart.app/api/hds/shares", {
    method: "POST",
    headers: { Authorization: `Bearer ${userToken}`, "Content-Type": "application/json" },
    body: JSON.stringify({ vaultId, targetUserId: recipientSub, level: "READ" }),
  });
  if (response.status !== 201) throw new Error(`${response.status} ${await response.text()}`);
  return (await response.json()) as { shareId: string; active: boolean };
}
```
:::
::::

Réponse attendue (`201 Created`) :

```json
{
  "shareId": "shr_Wq2Ez5Rt",
  "vaultId": "vlt_a1B2c3D4",
  "targetUserId": "2c9d7e41-5a8b-4f60-9e3d-1b7a6c5d4e21",
  "targetTeamId": null,
  "targetRole": null,
  "level": "READ",
  "grantedBy": "8f14e45f-ceea-467f-a0e6-2d2d3a7c1b11",
  "expiresAt": null,
  "active": true,
  "revokedAt": null,
  "revokedBy": null,
  "createdAt": "2026-10-23T11:15:30.200Z",
  "updatedAt": "2026-10-23T11:15:30.200Z"
}
```

`level` vaut `READ`, `READ_WRITE` ou `FULL_CONTROL` et consigne le niveau d'accès que vous accordez. Les opérations permises au destinataire restent fixées par ses rôles HDS.

## Consulter les partages

```bash
curl "https://api.wakastart.app/api/hds/shares?vaultId=vlt_a1B2c3D4&active=true" \
  -H "Authorization: Bearer $USER_TOKEN"
```

La liste contient les partages que vous avez accordés et ceux dont vous êtes le destinataire. Filtres : `vaultId`, `targetUserId`, `active` (`true` ou `false`), `limit` (20 par défaut, 100 au plus).

## Révoquer un partage

Seul l'auteur du partage le révoque, avec le rôle `HDS_DELETE` ou `HDS_ADMIN`.

```bash
curl -X DELETE "https://api.wakastart.app/api/hds/shares/shr_Wq2Ez5Rt" \
  -H "Authorization: Bearer $USER_TOKEN"
```

La réponse renvoie le partage avec `"active": false`, `revokedAt` et `revokedBy`. Le destinataire perd l'accès au coffre immédiatement.

## Vérifier le résultat

1. Avec le jeton du destinataire, appelez `GET /api/hds/vaults` : le coffre partagé figure dans la liste.
2. Après révocation, la même requête ne le renvoie plus, et `GET /api/hds/vaults/vlt_a1B2c3D4` répond `404`.

## Dépannage

- `400` `At least one target must be specified: …` : renseignez `targetUserId`.
- `403` `Insufficient HDS permissions for this operation` : vous n'avez ni `HDS_HEALTHCARE` ni `HDS_ADMIN`.
- `403` `You must be the vault owner or have an admin role to create shares` : vous n'êtes pas propriétaire du coffre.
- `404` `Share not found: …` à la révocation : vous n'êtes pas l'auteur de ce partage.

## Voir aussi

- [Mener une revue des accès](/v1.0/hds/mener-une-revue-des-acces)
- [Rôles HDS et règles d'accès](/v1.0/hds/roles-et-acces)
