Authentification

Chaque requête porte une clé API en tant que jeton Bearer :

curl https://www.sway.events/api/v1/artists \
  -H "Authorization: Bearer sway_sk_VOTRE_CLE"

La clé identifie votre crew. Il n'existe aucun paramètre de tenant dans l'API : ce qu'une clé peut voir est décidé par le crew auquel elle appartient, jamais par la requête.

Deux types de clé

Utilisez une clé secrète pour tout ce que fait votre serveur, et pour tout ce qui écrit, vend des billets ou touche des membres. Ne l'envoyez jamais à un navigateur ou une application : quiconque peut lire vos pages peut lire la clé.

Utilisez une clé publique quand un navigateur doit appeler l'API directement, par exemple un site statique sans serveur. Elle ne lit que ce que Sway affiche déjà publiquement, ne répond que sur ses propres sites web, et reçoit une allocation plus petite par adresse de visiteur, en plus de celle de la clé.

Cycle de vie d'une clé

Les clés se gèrent dans Admin crew → API (formules Studio et Roster, permission Gérer l'API).

Clé révoquée, expirée ou inconnue : la réponse est toujours la même, 401 invalid_key. L'API ne dit jamais à qui l'appelle si une clé qu'elle ne connaît pas a un jour existé. Le panneau Activité de chaque clé montre ce qu'elle a consommé de ses limites et ses derniers appels.

Si l'abonnement du crew expire, chaque clé répond 403 subscription_required jusqu'à sa réactivation.

Scopes

Les scopes sont choisis à la création de la clé et peuvent être modifiés ensuite. Une requête sans le scope requis par son endpoint répond 403 missing_scope.

GET /v1/me, /v1/usage, /v1/audit-log et /v1/genres ne demandent aucun scope : toute clé valide peut les appeler.

Les scopes "propriétaire du crew uniquement" ne peuvent être accordés que par le propriétaire du crew ; un membre détenant la permission Gérer l'API peut les retirer mais pas les ajouter. GET /v1/scopes renvoie cette liste en JSON.

Sites web et adresses du site

Deux listes d'adresses vivent sur une clé, toutes deux réglées dans Admin crew → API :

• Sites web (clés publiques) : les seules origines de navigateur auxquelles la clé répond. Une requête venant d'un autre site répond 403 origin_not_allowed.
• Adresses du site (clés avec un scope ambassadeur) : où Sway peut renvoyer un membre après un lien de connexion envoyé par e-mail. Votre site transmet l'adresse de retour avec la requête ; Sway ne l'accepte que si son origine figure sur la liste, si bien que le lien ne peut jamais pointer ailleurs. Une clé avec un scope ambassadeur et une liste vide sert quand même les pages, mais ne peut jamais reconnecter un membre.

Seules les origines https sont acceptées, plus http sur localhost pour le développement. Les chemins sont supprimés : seule l'origine est stockée et comparée.

Limites de débit

L'API est construite pour qu'un site partenaire à fort trafic continue d'afficher ses données. Deux idées portent cela :

• Une réponse en cache est gratuite. Les lectures sont mises en cache par crew. Répéter une requête que le cache détient déjà ne coûte rien, et un 304 Not Modified ne coûte rien.
• C'est le travail qui est compté, pas les requêtes. Seule une requête qui doit lire la base de données dépense le budget de travail de la clé, et elle le dépense en proportion de ce qu'elle lit.

Ce que coûte une requête non mise en cache :

Quand le budget est épuisé, une lecture que le cache détient reste servie, depuis la dernière copie, avec Cache-Status: sway; hit; ...; detail=rate-limited. Seule une lecture sans aucune copie répond 429 rate_limited, avec Retry-After.

Autres allocations, par clé sauf mention contraire :

Chaque réponse authentifiée indique le budget de travail de la clé :

RateLimit-Policy: "burst";q=120;w=60, "daily";q=20000;w=86400
RateLimit: "burst";r=118;t=42, "daily";r=19873;t=51230
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1759525489

RateLimit-Policy et RateLimit suivent le brouillon IETF ; les en-têtes X-RateLimit-* montrent la plus stricte des deux fenêtres et restent pour les clients existants. Sur un 429, attendez le nombre de secondes donné par Retry-After ; une clé qui continue de heurter la limite reçoit des attentes plus longues. Une clé qui parcourt des ids selon un motif inhabituel est limitée aux réponses en cache pendant un moment.

Mise en cache

Chaque lecture pouvant être mise en cache porte sa durée de vie et un ETag :

Cache-Control: private, max-age=60, stale-while-revalidate=120, stale-if-error=86400
ETag: "4f9a1c7e2b8d5f3a"
Cache-Status: sway; hit; ttl=42

Renvoyez l'ETag en If-None-Match : quand rien n'a changé, la réponse est 304 Not Modified, sans corps et sans coût. Cache-Status dit d'où vient une réponse : hit (le cache), fwd=miss (lecture fraîche), fwd=stale (rafraîchie après la fin de sa durée de vie). Les durées de vie vont de 30 secondes (catégories de billets, disponibilité) à une heure (genres) ; la référence des endpoints donne chacune d'elles. Les réponses qui portent des données propres à la clé ou à un membre ne sont jamais mises en cache (Cache-Control: private, no-store).

Pour passer outre la copie de Sway, envoyez Cache-Control: no-cache avec une clé secrète : la requête est relue à la source (Cache-Status: sway; fwd=request; stored) et dépense du travail comme toute lecture hors cache. C'est la requête à faire quand un webhook annonce un changement, car la copie peut dater d'avant. Quand votre budget de travail est épuisé, vous recevez quand même la copie, avec detail=rate-limited. Le Cache-Control d'une clé publique est ignoré.

Erreurs

Chaque erreur est un corps RFC 9457 application/problem+json, avec un code stable sur lequel brancher votre logique, et l'id de la requête :

{
  "type": "https://www.sway.events/en/docs/api/errors#missing_scope",
  "title": "Missing Scope",
  "status": 403,
  "detail": "This API key does not have the required scope.",
  "instance": "/api/v1/events/4521",
  "code": "missing_scope",
  "request_id": "0b7c2e4a-9f1d-4a3b-8c6e-5d2f1a9b7e3c"
}

validation_error porte aussi un tableau errors d'objets { "param", "message" }. Les endpoints ajoutent leurs propres codes là où il en faut (une catégorie épuisée, un code qui ne s'applique pas) ; la référence des endpoints les liste.

404 not_found vaut à la fois pour "n'existe pas" et "n'est pas à vous" : l'API ne confirme jamais l'existence de données en dehors de votre crew.

Chaque réponse, succès ou erreur, porte X-Request-Id. Citez-le quand vous nous contactez : il retrouve la requête dans nos logs. Vous pouvez envoyer votre propre X-Request-Id (8 à 128 lettres, chiffres, ., _, : ou -) pour relier nos logs aux vôtres ; toute autre valeur est remplacée par un nouvel id.

Idempotence

Une nouvelle tentative réseau ne doit jamais réserver, inscrire ou rembourser deux fois. Envoyez un en-tête Idempotency-Key sur un POST, une valeur unique par opération (un UUID est idéal, 1 à 255 caractères ASCII visibles) :

curl -X POST https://www.sway.events/api/v1/booking-requests \
  -H "Authorization: Bearer sway_sk_VOTRE_CLE" \
  -H "Idempotency-Key: 5b8f3c1e-2a7d-4e9b-8c6f-1d3a5e7b9c2f" \
  -H "Content-Type: application/json" \
  -d '{ "artist_ids": [501], "event_name": "Warehouse Series #4", "contact_email": "[email protected]" }'

• La même clé avec le même corps dans les 24 heures reçoit la première réponse en retour, sans refaire le travail.
• La même clé avec un autre corps répond 422 idempotency_mismatch.
• Une nouvelle tentative qui arrive pendant que la première requête tourne encore répond 409 conflict : attendez et réessayez.

Cela fonctionne sur chaque POST sauf l'ouverture d'un paiement, qui se protège elle-même des doublons, et les vérifications de coupons et codes d'accès, qui ne changent rien. Une réponse qui porte un secret (une clé qui vient de tourner) n'est jamais conservée pour être rejouée.