SVAOAuthClient API

Complete reference for the SVAOAuthClient class.

Class Definition

class SVAOAuthClient:
    """SVA OAuth 2.0 Client with PKCE support."""

Constructor

SVAOAuthClient(
    base_url: str,
    client_id: str,
    client_secret: str,
    redirect_uri: str,
    data_token_secret: str,
    data_token_algorithm: str = 'HS256',
    scopes: Optional[str] = None
)

Parameters

Parameter	Type	Required	Description
base_url	str	Yes	Base URL of SVA OAuth provider
client_id	str	Yes	OAuth client ID
client_secret	str	Yes	OAuth client secret
redirect_uri	str	Yes	Redirect URI registered in OAuth app
data_token_secret	str	Yes	Secret for verifying data_token JWT
data_token_algorithm	str	No	JWT algorithm (default: 'HS256')
scopes	str	No	Space-separated scopes (default: 'openid email profile')

Example

from sva_oauth_client.client import SVAOAuthClient

client = SVAOAuthClient(
    base_url='https://auth.getsva.com',
    client_id='your_client_id',
    client_secret='your_client_secret',
    redirect_uri='https://yourapp.com/oauth/callback/',
    data_token_secret='your_data_token_secret',
    scopes='openid email profile username',
)

Methods

get_authorization_url()

Generate authorization URL and code verifier for PKCE.

def get_authorization_url(
    self,
    state: Optional[str] = None,
    code_verifier: Optional[str] = None,
    additional_params: Optional[Dict[str, str]] = None
) -> tuple[str, str]

Parameters

Parameter	Type	Required	Description
state	str	No	State parameter for CSRF protection (auto-generated if None)
code_verifier	str	No	Code verifier for PKCE (auto-generated if None)
additional_params	Dict[str, str]	No	Additional query parameters

Returns

tuple[str, str] - (authorization_url, code_verifier)

Example

auth_url, code_verifier = client.get_authorization_url()

# Store code_verifier in session
request.session['code_verifier'] = code_verifier

# Redirect user to auth_url
return redirect(auth_url)

exchange_code_for_tokens()

Exchange authorization code for access tokens.

def exchange_code_for_tokens(
    self,
    code: str,
    code_verifier: str,
    state: Optional[str] = None
) -> Dict[str, Any]

Parameters

Parameter	Type	Required	Description
code	str	Yes	Authorization code from callback
code_verifier	str	Yes	Code verifier used in authorization
state	str	No	State parameter for validation

Returns

Dict[str, Any] - Token response:

{
    'access_token': str,
    'refresh_token': str,
    'data_token': str,
    'scope': str,
    'expires_in': int,
    'token_type': str
}

Raises

• SVATokenError - If token exchange fails

Example

code = request.GET.get('code')
code_verifier = request.session.get('code_verifier')

tokens = client.exchange_code_for_tokens(code, code_verifier)

# Store tokens in session
request.session['sva_oauth_access_token'] = tokens['access_token']
request.session['sva_oauth_refresh_token'] = tokens['refresh_token']
request.session['sva_oauth_data_token'] = tokens['data_token']

refresh_access_token()

Refresh access token using refresh token.

def refresh_access_token(self, refresh_token: str) -> Dict[str, Any]

Parameters

Parameter	Type	Required	Description
refresh_token	str	Yes	Refresh token from previous authentication

Returns

Dict[str, Any] - New token response (same structure as exchange_code_for_tokens)

Raises

• SVATokenError - If token refresh fails

Example

refresh_token = request.session.get('sva_oauth_refresh_token')
new_tokens = client.refresh_access_token(refresh_token)

# Update session with new tokens
request.session['sva_oauth_access_token'] = new_tokens['access_token']

get_userinfo()

Get user information from OAuth provider.

def get_userinfo(self, access_token: str) -> Dict[str, Any]

Parameters

Parameter	Type	Required	Description
access_token	str	Yes	OAuth access token

Returns

Dict[str, Any] - User information dictionary

Raises

• SVATokenError - If userinfo request fails

Example

access_token = request.session.get('sva_oauth_access_token')
userinfo = client.get_userinfo(access_token)

decode_data_token()

Decode and verify data_token JWT.

def decode_data_token(self, data_token: str) -> Dict[str, Any]

Parameters

Parameter	Type	Required	Description
data_token	str	Yes	JWT data token from token response

Returns

Dict[str, Any] - Decoded token payload

Raises

• SVATokenError - If token is invalid or expired

Example

data_token = request.session.get('sva_oauth_data_token')
decoded = client.decode_data_token(data_token)

# Access claims
claims = decoded.get('claims', {})
email = claims.get('email')

get_blocks_data()

Extract blocks data from data_token.

def get_blocks_data(self, data_token: str) -> Dict[str, Any]

Parameters

Parameter	Type	Required	Description
data_token	str	Yes	JWT data token from token response

Returns

Dict[str, Any] - Dictionary containing identity blocks data (claims)

Raises

• SVATokenError - If token is invalid or expired

Example

data_token = request.session.get('sva_oauth_data_token')
blocks_data = client.get_blocks_data(data_token)

# Access blocks
email = blocks_data.get('email')
name = blocks_data.get('name')

Static Methods

generate_code_verifier()

Generate a random code verifier for PKCE.

@staticmethod
def generate_code_verifier() -> str

Returns

str - Base64 URL-safe encoded random string

Example

code_verifier = SVAOAuthClient.generate_code_verifier()

generate_code_challenge()

Generate code challenge from verifier using S256.

@staticmethod
def generate_code_challenge(verifier: str) -> str

Parameters

Parameter	Type	Required	Description
verifier	str	Yes	Code verifier string

Returns

str - Base64 URL-safe encoded SHA256 hash

Example

verifier = SVAOAuthClient.generate_code_verifier()
challenge = SVAOAuthClient.generate_code_challenge(verifier)

Exceptions

SVAOAuthError

Base exception for all SVA OAuth errors.

class SVAOAuthError(Exception):
    """Base exception for SVA OAuth errors."""
    pass

SVATokenError

Raised when token operations fail.

class SVATokenError(SVAOAuthError):
    """Exception raised when token operations fail."""
    pass

SVAAuthorizationError

Raised when authorization fails.

class SVAAuthorizationError(SVAOAuthError):
    """Exception raised when authorization fails."""
    pass

Complete Example

from sva_oauth_client.client import SVAOAuthClient, SVATokenError

# Initialize client
client = SVAOAuthClient(
    base_url='https://auth.getsva.com',
    client_id='your_client_id',
    client_secret='your_client_secret',
    redirect_uri='https://yourapp.com/oauth/callback/',
    data_token_secret='your_data_token_secret',
)

# Step 1: Get authorization URL
auth_url, code_verifier = client.get_authorization_url()
request.session['code_verifier'] = code_verifier
return redirect(auth_url)

# Step 2: Exchange code for tokens (in callback)
try:
    code = request.GET.get('code')
    code_verifier = request.session.get('code_verifier')
    
    tokens = client.exchange_code_for_tokens(code, code_verifier)
    
    # Store tokens
    request.session['sva_oauth_access_token'] = tokens['access_token']
    request.session['sva_oauth_refresh_token'] = tokens['refresh_token']
    request.session['sva_oauth_data_token'] = tokens['data_token']
    
    # Get blocks data
    blocks_data = client.get_blocks_data(tokens['data_token'])
    
except SVATokenError as e:
    # Handle error
    print(f"Token error: {e}")

Next Steps

• Learn about Decorators for view protection
• Explore Utilities for helper functions
• Check Endpoints for built-in views