Skip to main content

Token Management

Complete guide to managing OAuth tokens in your application.

Token Types​

SVA OAuth provides three types of tokens:

  1. Access Token - Used for API authentication (expires in 1 hour)
  2. Refresh Token - Used to refresh access tokens (expires in 30 days)
  3. Data Token - Contains user identity claims (expires in 5 minutes)

Automatic Token Refresh​

The TokenRefreshMiddleware automatically refreshes tokens:

# settings.py
MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware',
    # ... other middleware
    'sva_oauth_client.middleware.TokenRefreshMiddleware',
]

How It Works​

  1. Checks token expiry on each request
  2. Refreshes if token expires within 60 seconds
  3. Updates session with new tokens
  4. Handles failures gracefully

Manual Token Refresh​

Refresh tokens manually if needed:

from sva_oauth_client.client import get_client_from_settings, SVATokenError
from sva_oauth_client.utils import get_access_token

def refresh_token_manually(request):
    """Manually refresh access token"""
    refresh_token = request.session.get('sva_oauth_refresh_token')
    
    if not refresh_token:
        return False
    
    try:
        client = get_client_from_settings()
        new_tokens = client.refresh_access_token(refresh_token)
        
        # Update session
        request.session['sva_oauth_access_token'] = new_tokens['access_token']
        
        if 'refresh_token' in new_tokens:
            request.session['sva_oauth_refresh_token'] = new_tokens['refresh_token']
        
        if 'data_token' in new_tokens:
            request.session['sva_oauth_data_token'] = new_tokens['data_token']
        
        # Update expiry
        from datetime import datetime, timezone
        new_expires_in = new_tokens.get('expires_in', 3600)
        new_expiry = datetime.now(timezone.utc).timestamp() + new_expires_in
        request.session['sva_access_token_expiry'] = new_expiry
        
        return True
    except SVATokenError:
        return False

Token Storage​

Tokens are stored in Django session:

# Session keys
request.session['sva_oauth_access_token']  # Access token
request.session['sva_oauth_refresh_token']  # Refresh token
request.session['sva_oauth_data_token']    # Data token
request.session['sva_oauth_scope']         # Approved scopes
request.session['sva_access_token_expiry']  # Expiry timestamp
request.session['sva_remember_me']          # Remember me preference

Token Expiration​

Access Token​

  • Lifetime: 1 hour (default)
  • Usage: API authentication
  • Refresh: Automatic via middleware

Refresh Token​

  • Lifetime: 30 days (default)
  • Usage: Token renewal
  • Refresh: Included in refresh response (may rotate)

Data Token​

  • Lifetime: 5 minutes (default)
  • Usage: User identity claims
  • Refresh: New token on re-authentication

Checking Token Status​

Check if Authenticated​

from sva_oauth_client.utils import is_authenticated

if is_authenticated(request.session):
    # User is authenticated
    pass

Check Token Expiry​

from datetime import datetime, timezone

access_token_expiry = request.session.get('sva_access_token_expiry')

if access_token_expiry:
    expiry_datetime = datetime.fromtimestamp(access_token_expiry, tz=timezone.utc)
    now = datetime.now(timezone.utc)
    time_until_expiry = (expiry_datetime - now).total_seconds()
    
    if time_until_expiry <= 0:
        # Token expired
        pass

Token Errors​

Handling Token Errors​

from sva_oauth_client.utils import get_sva_claims
from sva_oauth_client.client import SVATokenError

try:
    claims = get_sva_claims(request)
except SVATokenError:
    # Token expired or invalid
    # User will be logged out automatically
    pass

Token Refresh Failures​

If token refresh fails:

  1. User is logged out automatically
  2. Session is cleared
  3. User is redirected to login

Remember Me​

Enabling Remember Me​

<!-- Login form -->
<form method="post" action="{% url 'sva_oauth_client:login' %}">
    {% csrf_token %}
    <label>
        <input type="checkbox" name="remember_me" value="true">
        Remember me for 30 days
    </label>
    <button type="submit">Sign In</button>
</form>

Session Expiry​

  • With Remember Me: Session expires in 30 days
  • Without Remember Me: Session expires when browser closes

Token Revocation​

Logout​

Logout clears all tokens:

from sva_oauth_client.utils import clear_oauth_session

def logout(request):
    clear_oauth_session(request.session)
    return redirect('/')

Or use the built-in view:

# urls.py
path('oauth/', include('sva_oauth_client.urls')),

# Template
<a href="{% url 'sva_oauth_client:logout' %}">Logout</a>

Best Practices​

  1. Use middleware - Automatic token refresh
  2. Handle errors - Token expiration and refresh failures
  3. Secure storage - Tokens in server-side session
  4. Monitor expiry - Check token status regularly
  5. Clear on logout - Remove all tokens on logout

Next Steps​