Skip to content

domain.enums.rate_limit_scope

src.domain.enums.rate_limit_scope

Rate Limit enumeration types.

Defines scoping strategies for rate limit rules. Each scope determines how rate limit keys are constructed and how limits are applied.

Architectural Decision

Following centralized enum pattern (see docs/architecture/directory-structure.md). All domain enums live in src/domain/enums/ for discoverability.

Usage

from src.domain.enums import RateLimitScope

rule = RateLimitRule( max_tokens=5, refill_rate=5.0, scope=RateLimitScope.IP, cost=1, enabled=True, )

Classes

RateLimitScope

Bases: str, Enum

Scope types for rate limit rules.

Determines how rate limit keys are constructed and how limits are applied to different types of identifiers.

String Enum

Inherits from str for easy serialization and database storage. Values are snake_case strings for consistency.

Key Formats

IP: rate_limit:ip:{address}:{endpoint} USER: rate_limit:user:{user_id}:{endpoint} USER_PROVIDER: rate_limit:user_provider:{user_id}:{provider}:{endpoint} GLOBAL: rate_limit:global:{endpoint}

Usage Examples
  • IP scope for unauthenticated endpoints (login, register)
  • USER scope for authenticated API endpoints
  • USER_PROVIDER scope for provider-specific operations (sync, refresh)
  • GLOBAL scope for system-wide limits (rare)
Source code in src/domain/enums/rate_limit_scope.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class RateLimitScope(str, Enum):
    """Scope types for rate limit rules.

    Determines how rate limit keys are constructed and how limits are
    applied to different types of identifiers.

    String Enum:
        Inherits from str for easy serialization and database storage.
        Values are snake_case strings for consistency.

    Key Formats:
        IP: rate_limit:ip:{address}:{endpoint}
        USER: rate_limit:user:{user_id}:{endpoint}
        USER_PROVIDER: rate_limit:user_provider:{user_id}:{provider}:{endpoint}
        GLOBAL: rate_limit:global:{endpoint}

    Usage Examples:
        - IP scope for unauthenticated endpoints (login, register)
        - USER scope for authenticated API endpoints
        - USER_PROVIDER scope for provider-specific operations (sync, refresh)
        - GLOBAL scope for system-wide limits (rare)
    """

    IP = "ip"
    """Rate limit by client IP address.

    Use for unauthenticated endpoints where user identity is unknown.
    Key format: rate_limit:ip:{ip_address}:{endpoint}

    Examples:
        - POST /api/v1/sessions (login)
        - POST /api/v1/users (registration)
        - POST /api/v1/password-reset-tokens

    Security:
        Protects against brute force attacks from single IP.
        Should handle X-Forwarded-For properly in production.
    """

    USER = "user"
    """Rate limit by authenticated user ID.

    Use for authenticated API endpoints where user identity is known.
    Key format: rate_limit:user:{user_id}:{endpoint}

    Examples:
        - GET /api/v1/accounts
        - GET /api/v1/transactions
        - PATCH /api/v1/users/me

    Note:
        More generous limits than IP scope (trusted users).
        Prevents single user from monopolizing resources.
    """

    USER_PROVIDER = "user_provider"
    """Rate limit by user + provider combination.

    Use for provider-specific operations where each provider has its own limits.
    Key format: rate_limit:user_provider:{user_id}:{provider_name}:{endpoint}

    Examples:
        - POST /api/v1/providers/{provider_id}/syncs
        - POST /api/v1/providers/{provider_id}/token-refreshes

    Note:
        Prevents excessive calls to third-party provider APIs.
        Respects provider-specific rate limits (e.g., Schwab: 120/min).
    """

    GLOBAL = "global"
    """Rate limit globally across all users.

    Use sparingly for system-wide limits that apply to all requests.
    Key format: rate_limit:global:{endpoint}

    Examples:
        - System health check endpoints
        - Public status endpoints

    Warning:
        Use rarely - shared limit means one user can exhaust limit for all.
        Consider USER scope with generous limits instead.
    """
Attributes
IP class-attribute instance-attribute 
IP = 'ip'

Rate limit by client IP address.

Use for unauthenticated endpoints where user identity is unknown. Key format: rate_limit:ip:{ip_address}:{endpoint}

Examples:

  • POST /api/v1/sessions (login)
  • POST /api/v1/users (registration)
  • POST /api/v1/password-reset-tokens
Security

Protects against brute force attacks from single IP. Should handle X-Forwarded-For properly in production.

USER class-attribute instance-attribute 
USER = 'user'

Rate limit by authenticated user ID.

Use for authenticated API endpoints where user identity is known. Key format: rate_limit:user:{user_id}:{endpoint}

Examples:

  • GET /api/v1/accounts
  • GET /api/v1/transactions
  • PATCH /api/v1/users/me
Note

More generous limits than IP scope (trusted users). Prevents single user from monopolizing resources.

USER_PROVIDER class-attribute instance-attribute 
USER_PROVIDER = 'user_provider'

Rate limit by user + provider combination.

Use for provider-specific operations where each provider has its own limits. Key format: rate_limit:user_provider:{user_id}:{provider_name}:{endpoint}

Examples:

  • POST /api/v1/providers/{provider_id}/syncs
  • POST /api/v1/providers/{provider_id}/token-refreshes
Note

Prevents excessive calls to third-party provider APIs. Respects provider-specific rate limits (e.g., Schwab: 120/min).

GLOBAL class-attribute instance-attribute 
GLOBAL = 'global'

Rate limit globally across all users.

Use sparingly for system-wide limits that apply to all requests. Key format: rate_limit:global:{endpoint}

Examples:

  • System health check endpoints
  • Public status endpoints
Warning

Use rarely - shared limit means one user can exhaust limit for all. Consider USER scope with generous limits instead.