Autorisations, erreurs et limites

Autorisations (scopes)

Un client demande des autorisations lors de son enregistrement ; le membre les voit sur la page de consentement.

Scope	Qui	Quoi
profile:read	membre	GET /v1/me — nom, e-mail, coordonnées, données de naissance, le code fiscal quand il y en a un, et la façon dont la personne est identifiée (codicefiscale_check)
profile:write	membre	PATCH /v1/me — téléphone, genre, et l’identification : date, lieu et pays de naissance, code fiscal (facultatif, peut être ajouté plus tard ; revalidé)
membership:read	membre	GET /v1/me/membership, /events, /statuto, /card
membership:request	membre	POST /v1/me/membership — demande d’adhésion
statuto:accept	membre	POST /v1/me/membership/statuto/accept
network:manage	membre	le consentement du membre aux circuits (bientôt)
memberships:read	client	GET /v1/memberships/{id}/status
verify:read	client	vérification des cartes au-delà du quota anonyme
identity:signup	client	POST /v1/signup — créer des comptes au nom des membres (intégrations serveur)
enroll:write	client	POST /v1/enroll — envoyer des demandes d’adhésion, avec ou sans code fiscal (guide)
events:read	membre	GET /v1/events, /v1/events/{slug}, /eligibility — événements réservés aux membres compris (guide)
registrations:read	membre, client	GET /v1/me/registrations (membre) ; GET /v1/events/{slug}/registrations (client, sans données personnelles)
registrations:write	membre, client	POST /v1/events/{slug}/registrations et DELETE /v1/me/registrations/{id} (membre) ; POST …/registrations/guest (client)
checkins:write	client	POST /v1/checkins — contrôles à l’entrée à partir d’une carte ou d’une inscription
webhooks:manage	client	bientôt

Un client public ou natif ne peut demander que des autorisations « membre » ; les autorisations « client » exigent un client confidentiel. Une personne qui n’est pas encore membre ne peut accorder que les autorisations d’adhésion (profile:*, membership:read, membership:request, statuto:accept).

Erreurs

Les réponses d’erreur sont en application/problem+json (RFC 9457) :

{
  "type": "https://developers.vimine.network/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Missing scope: profile:write",
  "request_id": "…"
}

code est stable : c’est lui qu’il faut tester. errors[] accompagne validation_failed et identification_required ({ field, code }). Une entrée codicefiscale_mismatch — un code fiscal en désaccord avec les données de naissance de la personne — porte aussi mismatches, hints et confirmable : quand confirmable vaut true, la personne peut confirmer le code et la requête est répétée avec codicefiscale_confirmed: true (voir Membres sans code fiscal). Les endpoints OAuth (/v1/oauth/token, /revoke) répondent au format OAuth ({ error, error_description }).

code	Signification
missing_token, invalid_token, token_expired	401 — reconnectez-vous (le SDK rafraîchit et réessaie de lui-même)
insufficient_scope	403 — le jeton n’a pas cette autorisation
api_disabled	403 — l’association n’a pas activé l’API ou n’accepte pas de demandes
plan_limit	403 — la formule de l’association n’a plus de place pour un membre de plus (vérifiez aps.accepting_requests avant d’afficher le formulaire)
not_available	403 — l’association ne prend pas de demandes en ce moment : elle n’a pas encore accepté les accords de la plateforme ni enregistré son statuto, elle n’est pas prête, ou elle ne prend que les personnes qu’elle a invitées (la bêta privée) ; detail dit laquelle de ces raisons. Sur POST /v1/signup : pendant la bêta, les comptes sont créés sur invitation
not_found	404 — aussi pour les ressources d’autres associations
validation_failed	422 — voir errors[] (required, invalid, invalid_codicefiscale, codicefiscale_mismatch avec confirmable…)
identification_required	422 sur POST /v1/me/membership, 409 sur POST /v1/enroll/confirm — la personne n’est pas identifiée : il faut un code fiscal, ou la date, le lieu et le pays de naissance ; errors[] nomme ce qui manque
statuto_outdated, statuto_required	422 — indique la version du statuto en vigueur (detail)
rate_limited	429 — attendez Retry-After
unavailable	503 — réessayez dans un instant

OAuth : invalid_grant (code ou jeton de rafraîchissement invalide, expiré ou réutilisé), invalid_client, invalid_scope, unauthorized_client (client en attente d’activation), access_denied (le membre a annulé).

Dans le SDK, tout cela est une VimineError avec le même code.

La bêta privée

Vimine est en bêta privée : les personnes et les associations entrent sur invitation. Pour un client, cela signifie :

• POST /v1/signup répond 403 not_available et ne crée rien, sauf si Vimine a ouvert l’adhésion publique de votre association ;
• une association qui ne prend que les personnes qu’elle a invitées a aps.invitation_only: true et aps.accepting_requests: false dans son profil public (association(slug)) ; POST /v1/enroll et POST /v1/me/membership répondent 403 not_available. Une personne invitée adhère depuis le lien qu’elle reçoit par e-mail ;
• les sandbox restent ouvertes : les clients de test fonctionnent comme toujours.

Vérifiez aps.accepting_requests avant d’afficher un formulaire d’adhésion — pour la bêta comme pour tout le reste ; <vimine-events> et <vimine-enroll> le font déjà.

Limites

• Par adresse IP : 60 requêtes/minute sur les endpoints sensibles (vérification des cartes, code fiscal, jeton), 120/minute sur le reste ; RateLimit-* et Retry-After dans les réponses.
• POST /v1/me/membership accepte Idempotency-Key : la même clé dans les 24 heures renvoie la même réponse (le SDK en génère une par appel).
• Les réponses authentifiées sont en Cache-Control: no-store.
• Chaque réponse porte un request_id : citez-le quand vous signalez un problème.