Développez sur V-ENT

Obtenir l'accès

1. Postulez sur la page partenaires, en indiquant ce que vous construisez et les scopes dont vous avez besoin.
2. Un administrateur V-ENT examine la demande et approuve les scopes accordés. Il peut en accorder moins que demandé.
3. Générez une clé depuis votre page partenaire. Le secret n'est affiché qu'une fois, alors conservez-le avant de fermer l'onglet.

Une clé ne peut jamais porter un scope non accordé à votre organisation, quelle que soit la demande. Suspendre un partenaire arrête immédiatement toutes ses clés, sans attendre leur expiration.

Authentification

Envoyez la clé comme bearer token à chaque requête.

curl https://api.v-ent.co/api/v1/whoami/ \
  -H "Authorization: Bearer vent_pk_<key id>.<secret>"

whoami est le premier endpoint à appeler : il renvoie le partenaire auquel la clé appartient et les scopes exacts qu'elle porte, le moyen le plus rapide de distinguer une clé mal configurée d'une permission manquante.

Scopes

Chaque endpoint exige un scope. Ne demandez que ce que vous utilisez : une demande portant sur tout met plus de temps à être approuvée.

events:read

Read events, their schedule and their venues

events:tickets:read

Read ticket types and remaining capacity for events

tournaments:read

Read tournaments, formats, prize pools and schedules

tournaments:participants:read

Read who is registered for a tournament

tournaments:brackets:read

Read brackets, matches and results

teams:read

Read team profiles and rosters

players:read

Read public player profiles

players:stats:read

Read player win and loss records

rankings:read

Read platform rankings

Endpoints

Tous en lecture seule, tous sous /api/v1/. Les listes sont paginées et renvoient results, count et la page demandée.

curl "https://api.v-ent.co/api/v1/tournaments/?page=1" \
  -H "Authorization: Bearer vent_pk_<key id>.<secret>"

Toutes les réponses ont la même forme

Succès ou échec, ce sont les mêmes clés au premier niveau et rien d'autre. Branchez sur code, jamais sur message : le message est écrit pour une personne et peut être reformulé, le code est le contrat.

{ "status": "success", "data": { }, "message": "Tournaments" }

{ "status": "error", "code": "SCOPE_REQUIRED", "message": "…", "data": null }

Pagination

Toutes les listes se paginent de la même façon. page commence à 1, page_size vaut 25 par défaut et s'arrête à 100. Paginez avec has_more plutôt qu'en comptant : il vient de la même requête que les lignes et ne peut donc pas les contredire.

GET /api/v1/tournaments/?page=2&page_size=50

{ "results": [ … ], "page": 2, "page_size": 50, "total": 137, "has_more": true }

Indiquer que les données viennent de V-ENT

GET /api/v1/ contient un bloc brand avec les logos et la seule consigne à suivre : vous n'avez pas à aller chercher un logo sur le site à la taille où vous le trouvez. Aucune clé n'est nécessaire pour le lire, car qui évalue une intégration n'en a pas encore.

"brand": {
  "name": "V-ENT",
  "logo": "https://v-ent.co/images/logo_mark_red.png",
  "logo_svg": "https://v-ent.co/images/logo_mark_red.svg",
  "colour": "#ED1C24",
  "attribution": "Data from V-ENT"
}

Utilisez le logo pour indiquer la provenance des données, à ses propres proportions et pas en dessous de 24 px de haut. Ne le recolorez pas, ne l'étirez pas et ne l'employez pas d'une façon qui laisse croire que V-ENT recommande votre produit. Préférez le SVG : il reste net à toutes les tailles, ce que le PNG ne fera pas.

Limite de débit

60 requêtes par minute et par clé. Demandez si vous avez besoin de plus, en précisant pourquoi. Les classements et les tableaux terminés changent rarement : une minute de cache ne vous coûte rien et vous garde largement sous la limite.

Quatre choses à savoir avant de construire

Adressez les enregistrements par slug

Toutes les adresses V-ENT visibles utilisent le slug, et un enregistrement renommé garde ses anciennes adresses. C'est ce qu'il vous faut dans un lien vers nous.

Les montants sont des chaînes décimales

\"220000.00\", pas un nombre. Analysez-le comme un décimal. Une dotation passée par un flottant finira par s'afficher de travers.

Les heures sont en UTC, ISO 8601

Avec le Z à la fin. Convertissez pour vos propres lecteurs ; ne supposez pas Lagos.

Uniquement les enregistrements publics

Les brouillons, les tournois privés et tout ce qui appartient à un compte suspendu ne sont jamais renvoyés, et aucune portée ne les ouvre.

Connexion avec V-ENT

Flux authorization-code standard avec PKCE. Si vous avez déjà intégré « Connexion avec Google », vous connaissez la forme. Demandez à un administrateur V-ENT d'approuver le SSO pour votre compte partenaire et vous recevrez un client id et un secret, affiché une seule fois.

Scopes d'identité

• identity
• identity:email
• identity:teams

Créez d'abord une paire PKCE

Gardez le vérificateur dans la session du visiteur, sur votre serveur ; il ne la quitte jamais. N'envoyez que le défi. Si vous envoyez un défi, c'est lui qui est vérifié et votre secret client n'est pas consulté : c'est pourquoi une application navigateur n'en a jamais besoin.

const verifier  = base64url(randomBytes(32));   // keep this
const challenge = base64url(sha256(verifier));  // send this

1. Redirigez-les vers V-ENT

https://v-ent.co/partners/authorize
  ?client_id=vent_sso_<yours>
  &redirect_uri=https://your-site.example/callback
  &scope=identity identity:email
  &state=<random, checked when they come back>
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256

2. Échangez le code, depuis votre serveur

curl -X POST https://api.v-ent.co/partners/sso/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<the code on your callback>",
    "client_id": "vent_sso_<yours>",
    "client_secret": "<yours>",
    "redirect_uri": "https://your-site.example/callback",
    "code_verifier": "<the verifier you hashed>"
  }'

3. Lisez qui c'est

curl https://api.v-ent.co/partners/sso/userinfo/ \
  -H "Authorization: Bearer <access_token>"

Le code est à usage unique et de courte durée, et un mauvais vérifier PKCE est refusé. Échangez-le depuis votre serveur, jamais depuis le navigateur : le client secret ne doit pas atteindre une page lisible par tous.

Identifiez le compte par sub

Pas par le nom d'utilisateur. Une personne peut le changer ; sub reste stable toute la vie du compte et c'est le seul champ ici que vous pouvez utiliser comme clé primaire.

Toute personne connectée avec V-ENT peut retirer la connexion depuis son compte, et les jetons existants cessent alors de fonctionner. Traitez BAD_TOKEN en relançant le parcours, pas en conservant une session morte.

Aucune portée ne donne accès à un portefeuille, un solde, une transaction, un versement ou une pièce d'identité, et il n'y en aura pas. C'est inscrit dans le code, pas dans une politique.

Quand quelque chose ne va pas

Chaque échec renvoie un code lisible par machine en plus d'une phrase. Testez le code : la phrase peut être reformulée.

{ "status": "error", "code": "INVALID_KEY", "message": "That key is not valid.", "data": null }

MISSING_KEY

En-tête Authorization absent, ou ce n'est pas un bearer token.

MALFORMED_KEY

Ce n'est pas une clé V-ENT. Vérifiez le préfixe vent_pk_ et le point avant le secret. 401.

INVALID_KEY

Key id inconnu, secret incorrect, ou clé révoquée.

PARTNER_INACTIVE

Le compte partenaire est suspendu ou pas encore approuvé. Les clés cessent de fonctionner immédiatement, pas à l'émission suivante. 401.

SCOPE_REQUIRED

La clé est validé mais n'a pas été approuvée pour cet endpoint.

RATE_LIMITED

Trop de requêtes cette minute. Patientez et réessayez.

EVENT_NOT_FOUND

Aucun enregistrement de ce type, ou il n'est pas public. Un enregistrement privé répond 404 plutôt que 403, car dire qu'il existe est déjà une divulgation. Aussi TOURNAMENT_NOT_FOUND, TEAM_NOT_FOUND, PLAYER_NOT_FOUND. 404.