Crie na V-ENT

Obter acesso

1. Candidate-se na página de parceiros, indicando o que está a criar e os scopes de que precisa.
2. Um administrador da V-ENT analisa e aprova os scopes concedidos. Pode aprovar menos do que pediu.
3. Gere uma chave na sua página de parceiro. O segredo é mostrado uma única vez, por isso guarde-o antes de fechar o separador.

Uma chave nunca pode ter um scope que a sua organização não recebeu, seja qual for o pedido. Suspender um parceiro para imediatamente todas as suas chaves, sem esperar que expirem.

Autenticação

Envie a chave como bearer token em cada pedido.

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

whoami é o primeiro endpoint a chamar: devolve o parceiro a que a chave pertence e os scopes exatos que carrega, a forma mais rápida de distinguir uma chave mal configurada de uma permissão em falta.

Scopes

Cada endpoint exige um scope. Peça apenas o que usa: um pedido que abrange tudo demora mais a ser aprovado.

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

Todos apenas de leitura, todos em /api/v1/. As listas são paginadas e devolvem results, count e a página pedida.

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

Iniciar sessão com V-ENT

Fluxo authorization-code padrão com PKCE. Se já integrou o "Iniciar sessão com Google", conhece o formato. Peça a um administrador da V-ENT para aprovar o SSO na sua conta de parceiro e receberá um client id e um segredo, mostrado uma vez.

Scopes de identidade

• identity
• identity:email
• identity:teams

1. Encaminhe-os para a 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. Troque o código, a partir do seu servidor

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. Leia quem é

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

O código é de uso único e de curta duração, e um verifier PKCE errado é recusado. Faça a troca a partir do seu servidor, nunca do navegador: o client secret não pode chegar a uma página que qualquer pessoa possa ler.

Something Untranslated HereQuando algo corre mal

Cada falha devolve um código legível por máquina além de uma frase. Use o código: a frase pode ser reescrita.

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

MISSING_KEY

Cabeçalho Authorization em falta, ou não é um bearer token.

INVALID_KEY

Key id desconhecido, segredo errado, ou a chave foi revogada.

MISSING_SCOPE

A chave é válida mas não foi aprovada para este endpoint.

RATE_LIMITED

Demasiados pedidos neste minuto. Aguarde e tente novamente.