Quick Start¶

This guide will get you up and running with the Vairified Python SDK in minutes.

Installation¶

Install from PyPI using pip:

pip install vairified

Or with UV (recommended):

uv add vairified

Configuration¶

You’ll need a Partner API key from Vairified. You can pass it directly or use environment variables:

export VAIRIFIED_API_KEY="vair_pk_xxx"
export VAIRIFIED_ENV="next"  # Optional: production, next, staging, local

Basic Usage¶

The SDK uses an async context manager pattern:

import asyncio
from vairified import Vairified

async def main():
    async with Vairified(api_key="vair_pk_xxx") as client:
        # Your code here
        pass

asyncio.run(main())

Get a Member¶

Fetch a member by their Clerk user ID, member ID, or UUID:

member = await client.get_member("clerk_user_123")
print(f"{member.name}: {member.rating}")
print(f"Verified: {member.is_vairified}")

Search Players¶

Search with various filters:

results = await client.search(
    city="Austin",
    state="TX",
    rating_min=3.5,
    rating_max=4.5,
    vairified_only=True,
)

for player in results:
    print(f"{player.name}: {player.rating}")

# Pagination
if results.has_more:
    next_page = await results.next_page()

Submit Matches¶

Submit match results:

from datetime import datetime
from vairified import Match

# Doubles match
match = Match(
    event="Weekly League",
    bracket="4.0 Doubles",
    date=datetime.now(),
    team1=("player1_id", "player2_id"),
    team2=("player3_id", "player4_id"),
    scores=[(11, 9), (11, 7)],
)

result = await client.submit_match(match)
if result:
    print(f"Submitted {result.num_games} games")

Environment Selection¶

The SDK defaults to the production environment:

# Default (production)
client = Vairified(api_key="vair_pk_xxx")

# Staging for testing
client = Vairified(api_key="vair_pk_xxx", env="staging")

# Local development
client = Vairified(api_key="vair_pk_xxx", env="local")

Available environments:

Environment	Description
`production`	Live API (default)
`staging`	Testing environment
`local`	Local development

OAuth Connect Flow¶

Connect players to your application using OAuth:

import secrets
from vairified import Vairified

async with Vairified(api_key="vair_pk_xxx") as client:
    # Step 1: Start OAuth flow
    state = secrets.token_urlsafe(32)  # CSRF protection
    auth = await client.start_oauth(
        redirect_uri="https://your-app.com/callback",
        scopes=["profile:read", "rating:read"],
        state=state,
    )
    # Redirect user to auth.authorization_url

After the user approves, exchange the code for tokens:

# Step 2: Exchange code for tokens
tokens = await client.exchange_token(code, redirect_uri)

# Store tokens securely
player_id = tokens.player_id
access_token = tokens.access_token

# Step 3: Access connected player
member = await client.get_member(player_id)

Error Handling¶

The SDK provides typed exceptions:

from vairified import (
    VairifiedError,
    RateLimitError,
    AuthenticationError,
    NotFoundError,
    OAuthError,
)

try:
    member = await client.get_member("user_123")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Member not found")
except OAuthError as e:
    print(f"OAuth error: {e.message} (code: {e.error_code})")
except VairifiedError as e:
    print(f"API error: {e.message}")