Build on V-ENT

Getting access

1. Apply on the partners page, saying what you are building and which scopes you need.
2. A V-ENT admin reviews it and approves the scopes you may have. They can approve fewer than you asked for.
3. Issue a key from your partner page. The secret is shown once and never again, so store it before you close the tab.

A key can never carry a scope your organisation was not approved for, whatever the request asks for. Suspending a partner stops every key it owns immediately, without waiting for them to expire.

Authentication

Send the key as a bearer token on every request.

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

whoami is the endpoint to call first: it answers with the partner the key belongs to and the exact scopes it carries, which is the quickest way to tell a misconfigured key from a missing permission.

Scopes

Every endpoint needs one scope. Ask only for what you use: an application requesting everything takes longer to approve.

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

All read-only, all under /api/v1/. Lists are paginated and answer with results, count and the page you asked for.

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

Sign in with V-ENT

Standard authorization-code flow with PKCE. If you have integrated "Sign in with Google" you already know this shape. Ask a V-ENT admin to approve SSO for your partner account and you get a client id and a secret, shown once.

Identity scopes

• identity
• identity:email
• identity:teams

1. Send them to 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. Swap the code, on your server

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. Read who they are

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

The code is single use and short lived, and the wrong PKCE verifier is refused. Swap it from your server, never from the browser: the client secret must not reach a page anybody can read.

Something Untranslated HereWhen something is wrong

Every failure answers with a machine-readable code as well as a sentence. Branch on the code; the sentence may be reworded.

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

MISSING_KEY

No Authorization header, or not a bearer token.

INVALID_KEY

Unknown key id, wrong secret, or the key was revoked.

MISSING_SCOPE

The key is good but was not approved for this endpoint.

RATE_LIMITED

Too many requests this minute. Back off and retry.