Organisations & Workspaces

Aperçu

qr3.app utilise une hiérarchie à deux niveaux :

Organization (Firma/Agentur)
  └── Workspace 1 (Kunde A)
  └── Workspace 2 (Kunde B)
  └── Workspace 3 (Internes Team)

Organisation — niveau supérieur, associé à un compte Stripe et à un forfait
Workspace — espace isolé pour les codes QR, les scans et les clés API

API Organizations

`GET /v1/organizations`

Retourne l’organisation à laquelle appartient la clé API actuelle.

curl https://qr3.app/v1/organizations \
  -H "Authorization: Bearer qr3_sk_..."

`GET /v1/organizations/usage`

Retourne l’utilisation en temps réel de l’organisation par rapport aux limites du forfait — cumulée sur tous les workspaces et calculée en direct : scans pour le mois de facturation en cours (par rapport à max_scans_per_month) et dynamic_codes, le nombre de codes dynamiques actifs (par rapport à max_dynamic_codes). Aucun des deux n’est jamais bloqué lorsque la limite est de dépassement ; utilisez cet endpoint pour afficher l’utilisation et les invitations à passer au forfait supérieur.

curl https://qr3.app/v1/organizations/usage \
  -H "Authorization: Bearer qr3_sk_..."

{
  "data": {
    "scans": {
      "used": 4120,
      "limit": 5000,
      "usage_pct": 82,
      "remaining": 880,
      "period": "2026-06",
      "period_start": "2026-06-01T00:00:00.000Z"
    },
    "dynamic_codes": {
      "used": 142,
      "limit": 500,
      "usage_pct": 28,
      "remaining": 358
    }
  }
}

`POST /v1/organizations`

Crée une nouvelle organisation.

curl -X POST https://qr3.app/v1/organizations \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Digital Heroes GmbH",
    "slug": "digital-heroes",
    "billing_email": "[email protected]"
  }'

Champs :

Champ	Type	Requis	Description
`name`	string	✅	Nom d’affichage (max. 255 caractères)
`slug`	string	✅	Compatible URL, unique (min. 2, max. 63 caractères, uniquement `a-z0-9-`)
`billing_email`	string	—	E-mail de facturation

`PATCH /v1/organizations/:id`

Modifie le nom, l’e-mail de facturation et l’e-mail de notification de l’organisation.

Seul un org_admin peut les modifier, dans une session du tableau de bord. Les requêtes authentifiées avec une clé API sont rejetées avec 403 — clés qr3_sk_ et qr3_test_sk_ comprises —, une clé divulguée ne peut donc pas détourner l’adresse de facturation ou de notification.

`DELETE /v1/organizations/:id`

Suppression réversible (soft-delete) de l’organisation. Tous les workspaces et codes QR associés sont conservés, mais ne sont plus accessibles.

Requiert le rôle org_admin (session du tableau de bord). Les requêtes authentifiées avec une simple clé API sont rejetées avec 403 — les clés API ne possèdent jamais de rôle d’administrateur, une clé divulguée ne peut donc pas supprimer l’organisation.

API Workspaces

`GET /v1/workspaces`

Liste les workspaces visibles pour l’appelant : org_admin et le propriétaire de l’organisation voient tous les workspaces de l’organisation, les autres membres uniquement les workspaces auxquels ils appartiennent, et une clé API uniquement son propre workspace. Un workspace que l’appelant ne peut pas voir répond 404 sur chaque route /v1/workspaces/:id, exactement comme un ID inconnu.

curl https://qr3.app/v1/workspaces \
  -H "Authorization: Bearer qr3_sk_..."

`POST /v1/workspaces`

Créer un nouveau workspace.

curl -X POST https://qr3.app/v1/workspaces \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunde Bäckerei Schmidt",
    "slug": "baeckerei-schmidt",
    "default_locale": "de",
    "primary_color": "#8B4513",
    "approval_required": false
  }'

Avec une clé API, seule une clé créée par un org_admin ou par le propriétaire de l’organisation peut créer un workspace ; toute autre clé reçoit 403, avant même la vérification du slug (la réponse ne révèle donc pas quels slugs sont pris). Le rôle de la personne qui a créé la clé est vérifié à chaque requête : si elle est rétrogradée, sa clé perd ce droit. Une clé API est liée à son propre workspace et ne voit pas le nouveau ensuite : son id figure dans la réponse 201 ; un org_admin l’ouvre dans le tableau de bord et peut y créer une clé pour lui. Dans le tableau de bord, seul un org_admin peut créer des workspaces.

Champs :

Champ	Type	Par défaut	Description
`name`	string	—	Nom d’affichage (requis)
`slug`	string	—	Compatible URL, unique par organisation (requis)
`default_locale`	string	`de`	Langue par défaut
`approval_required`	boolean	`false`	Réservé au workflow d’approbation planifié (non implémenté)
`primary_color`	string	—	Couleur de marque (`#RRGGBB`)

Limites du forfait :

Forfait	Max. Workspaces
Free	1
Pro	1
Business	10
Agency	50
Enterprise	500

`PATCH /v1/workspaces/:id`

curl -X PATCH https://qr3.app/v1/workspaces/ws_xyz789 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neuer Name",
    "approval_required": true
  }'

`DELETE /v1/workspaces/:id`

Archive le workspace. Ne peut pas être appliqué à votre propre workspace.

Requiert org_admin ou ws_admin du workspace à archiver ; les autres rôles reçoivent 403. Un workspace que l’appelant ne peut pas voir répond 404 — pour une clé API, c’est le cas de tout workspace sauf le sien, qu’elle ne peut pas non plus archiver.

Journaux d’audit

`GET /v1/audit-logs`

Historique traçable de toutes les modifications apportées au workspace.

curl "https://qr3.app/v1/audit-logs?resource_type=codes&limit=50" \
  -H "Authorization: Bearer qr3_sk_..."

Paramètres de requête :

Paramètre	Type	Description
`resource_type`	string	Filtrer par ressource : `codes`, `api_keys`, `webhooks`, `workspaces`
`resource_id`	string	Filtrer par ID de ressource spécifique
`action`	string	Filtrer par action (par ex. `codes.created`)
`cursor`	string	Curseur de pagination
`limit`	integer	Max. 100 (par défaut : 50)

Exemple de réponse :

{
  "data": [
    {
      "id": "aud_a1b2c3",
      "actor_type": "api",
      "action": "codes.created",
      "resource_type": "codes",
      "resource_id": "qr_xyz123",
      "changes": {},
      "created_at": "2026-03-15T10:00:00.000Z"
    }
  ]
}