Authentification

Clés API, scopes, limites de débit et format des erreurs de l'API publique Sway.

Authentification

Chaque requête vers l'API publique Sway est authentifiée avec une clé API envoyée en tant que jeton Bearer :

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

Les clés commencent par le préfixe sway_sk_. La clé identifie votre crew — il n'existe aucun paramètre de tenant dans l'API.

Gardez votre clé côté serveur. N'appelez l'API que depuis votre propre backend. N'envoyez jamais la clé dans un navigateur, une application mobile ou du code côté client — quiconque peut lire vos pages pourrait l'extraire et lire vos données.

Cycle de vie d'une clé

Les clés se gèrent dans Admin crew → API (formules Studio et Roster).

Action	Comportement
Créer	Choisissez un nom, des scopes et une expiration optionnelle (30, 90 ou 365 jours, ou jamais). La clé complète n'est affichée qu'une seule fois — copiez-la immédiatement ; ensuite seuls le préfixe et les 4 derniers caractères sont visibles
Révoquer	Immédiat et irréversible. Les clés révoquées reçoivent `401 key_revoked` sur chaque requête
Expirer	Une fois `expires_at` dépassé, les requêtes reçoivent `401 key_expired`. Créez une nouvelle clé pour continuer
Faire tourner	Créez une nouvelle clé, déployez-la, puis révoquez l'ancienne

Si l'abonnement de votre crew expire, toutes les clés cessent de fonctionner avec 403 subscription_required jusqu'à la réactivation de l'abonnement.

Scopes

Les scopes sont choisis à la création de la clé. Les scopes de lecture contrôlent l'accès aux ressources ; la visibilité au niveau des champs est déterminée par la propriété (gérée vs publique), pas par les scopes.

Scope	Donne accès à
`read:profile`	`GET /v1/me`, `GET /v1/crew`
`read:artists`	Roster, détail artiste, événements d'un artiste
`read:promoters`	Promoteurs gérés et leurs événements
`read:events`	Détail événement, lineups, salles intégrées
`read:venues`	Détail salle (niveau public)
`write:bookings`	`POST /v1/booking-requests` (opt-in à la création de la clé)

Le modèle par défaut accorde tous les scopes read:* et aucun scope d'écriture. Une requête sans le scope requis renvoie 403 missing_scope.

Limites de débit

Chaque clé a deux limites — une fenêtre de rafale par minute et une fenêtre soutenue par jour — appliquées par clé. Les valeurs par défaut dépendent de votre formule :

Formule	Rafale (par minute)	Soutenue (par jour)
Studio	120	20 000
Roster	300	100 000

Chaque réponse authentifiée inclut l'état courant (la plus contraignante des deux fenêtres) :

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1751551260

Quand une limite est dépassée, l'API renvoie 429 avec un en-tête Retry-After (secondes à attendre). Patientez ce délai avant de réessayer.

Les en-têtes X-RateLimit-* ne sont pas envoyés sur les réponses d'échec d'authentification (401 invalid_key, 401 key_expired, 401 key_revoked) — ils n'apparaissent qu'une fois une clé valide identifiée.

Avec une mise en cache raisonnable (voir Intégration sur votre site), un site partenaire reste très en dessous des limites par défaut. Si vous avez besoin de limites plus élevées, contactez-nous — elles sont ajustables par clé.

Erreurs

Toutes les réponses 4xx/5xx utilisent le format RFC 9457 application/problem+json, avec un champ code stable sur lequel brancher votre logique :

{
  "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"
}

`code`	Statut HTTP	Signification
`invalid_key`	401	Clé malformée ou inconnue
`key_expired`	401	Clé au-delà de son `expires_at`
`key_revoked`	401	Clé révoquée
`subscription_required`	403	L'abonnement du crew n'inclut plus l'accès API
`missing_scope`	403	La clé n'a pas le scope requis par cet endpoint
`rate_limited`	429	Limite de débit dépassée — consultez `Retry-After`
`not_found`	404	La ressource n'existe pas ou est en dehors du graphe de votre crew
`validation_error`	400 / 422	Paramètre de requête invalide (400) ou corps de requête invalide (422)
`invalid_cursor`	400	Curseur de pagination malformé ou périmé
`internal_error`	500	Un problème de notre côté — vous pouvez réessayer

Au-delà des membres RFC 9457 standards (type, title, status, detail, instance), chaque problème porte le code machine ci-dessus. Les réponses validation_error incluent aussi un tableau errors d'objets { "param", "message" }.

404 not_found est volontairement utilisé à la fois pour les ressources inexistantes et inaccessibles — l'API ne confirme jamais l'existence de données en dehors du graphe de votre crew.

Aperçu de l'API

Intégrez vos données Sway sur votre propre site web avec l'API publique liée à votre crew.

Référence des endpoints

Référence complète de tous les endpoints de l'API publique Sway v1.