Authentification

Comment s'authentifier aupres de l'API Treats

Clé API

Toute requête vers l’API doit inclure une clé API valide dans le header HTTP X-API-Key.

curl -H "X-API-Key: vk_aBcDeFgHiJkL..." \
  https://app.treats.vet/api/v1/patients

Format de la clé

Les clés API Treats commencent toujours par le prefixe vk_ suivi de 32 octets aleatoires encodes en Base64 URL-safe sans remplissage (43 caracteres).

vk_dGhpcyBpcyBhIHNhbXBsZSBrZXk

Obtenir une clé

Les clés sont creees par l’administrateur de la clinique depuis le panneau d’administration Treats. Lors de la creation, la clé brute est affichée une seule fois. Elle ne peut pas être recuperee ensuite.

Stockez votre clé de maniere securisee (variable d’environnement, secret manager). Ne la commitez jamais dans votre code source.

Configuration de la clé

Chaque clé API est configurée avec :

Paramètre	Description	Exemple
Permissions	Endpoints accessibles	`PATIENT_READ`, `APPOINTMENT_CREATE`
Niveau d’accès par défaut	Visibilite des champs (`STANDARD` si non precise)	`STANDARD`
Scopes par ressource	Surcharge par type de donnée	`patient: FULL`, `client: BASIC`
Limite de requêtes	Requêtes par heure (`1000` si non precisee)	`1000`
Date d’expiration	Optionnelle	`2026-12-31`

Permissions disponibles

Permission	Accès
`PATIENT_READ`	`GET /patients`, `GET /patients/{id}`
`CLIENT_READ`	`GET /clients`, `GET /clients/{id}`
`APPOINTMENT_READ`	`GET /appointments/{id}`, `GET /appointments/types`, `GET /appointments/available-slots`
`APPOINTMENT_CREATE`	`POST /appointments` (pas encore ouverte aux clés API : la route répond `401`)
`CONSULTATION_READ`	`GET /consultations/{id}`
`INVOICE_READ`	`GET /invoices/{id}`, `GET /invoices/client/{clientId}`
`STOCK_READ`	`GET /stock`, `GET /stock/{stockId}`, `GET /stock/low`
`IMAGING_RESULT_WRITE`	`POST /imaging/picoxia/exams/{examId}/results`, `GET /imaging/picoxia/ping` (clé créée par la clinique à l’activation de Picoxia)

Si votre clé n’a pas la permission requise pour un endpoint, vous recevrez une erreur 403 Forbidden. Les chemins de ce tableau sont relatifs a https://app.treats.vet/api/v1.

Réponses d’erreur

Clé manquante

// 401 Unauthorized
{
  "message": "Authentication required"
}

Clé invalide, expirée ou révoquée

La réponse est la même que sans clé : l’API ne dit pas pourquoi la clé est refusée.

// 401 Unauthorized
{
  "message": "Authentication required"
}

Permission manquante

// 403 Forbidden
{
  "message": "Insufficient permissions",
  "code": "PERMISSION_REQUIRED"
}

Bonnes pratiques

Utilisez des variables d'environnement

Ne codez jamais la clé en dur dans votre application.

export TREATS_API_KEY=vk_votre_cle_ici

const apiKey = process.env.TREATS_API_KEY;

Demandez le minimum de permissions

Si votre intégration n’a besoin que de lire les patients, demandez uniquement PATIENT_READ. Moins de permissions = moins de risques en cas de fuite de la clé.

Utilisez des cles differentes par environnement

Creez une clé pour le developpement et une autre pour la production. Cela permet de révoquer l’une sans impacter l’autre.

Gerez l'expiration

Si votre clé à une date d’expiration, prevoyez un mecanisme de renouvellement aupres de l’administrateur de la clinique avant l’echeance.