Skip to content

schemas.rotation_schemas

src.schemas.rotation_schemas

Token rotation request/response schemas.

Pydantic models for admin API token rotation endpoints. Admin-only operations for breach response and security management.

RESTful Endpoints (admin-only): POST /api/v1/admin/security/rotations - Global token rotation POST /api/v1/admin/users/{user_id}/rotations - Per-user token rotation GET /api/v1/admin/security/config - Get security config

Classes

GlobalRotationRequest

Bases: BaseModel

Request schema for global token rotation.

POST /api/v1/admin/security/rotations Returns: 201 Created

Admin-only. Invalidates ALL tokens with version below new minimum.

Source code in src/schemas/rotation_schemas.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class GlobalRotationRequest(BaseModel):
    """Request schema for global token rotation.

    POST /api/v1/admin/security/rotations
    Returns: 201 Created

    Admin-only. Invalidates ALL tokens with version below new minimum.
    """

    reason: str = Field(
        ...,
        min_length=1,
        max_length=500,
        description="Reason for rotation (for audit trail)",
        examples=["Database breach detected", "Security vulnerability patched"],
    )

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "reason": "Database breach detected - rotating all tokens",
            }
        }
    )

GlobalRotationResponse

Bases: BaseModel

Response schema for global token rotation (201 Created).

Source code in src/schemas/rotation_schemas.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class GlobalRotationResponse(BaseModel):
    """Response schema for global token rotation (201 Created)."""

    previous_version: int = Field(
        ...,
        description="Previous global minimum token version",
    )
    new_version: int = Field(
        ...,
        description="New global minimum token version",
    )
    grace_period_seconds: int = Field(
        ...,
        description="Seconds before old tokens fully rejected",
    )
    message: str = Field(
        default="Global token rotation triggered successfully",
        description="Success message",
    )

UserRotationRequest

Bases: BaseModel

Request schema for per-user token rotation.

POST /api/v1/admin/users/{user_id}/rotations Returns: 201 Created

Admin operation. Invalidates only the specified user's tokens.

Source code in src/schemas/rotation_schemas.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
class UserRotationRequest(BaseModel):
    """Request schema for per-user token rotation.

    POST /api/v1/admin/users/{user_id}/rotations
    Returns: 201 Created

    Admin operation. Invalidates only the specified user's tokens.
    """

    reason: str = Field(
        ...,
        min_length=1,
        max_length=500,
        description="Reason for rotation (for audit trail)",
        examples=["Suspicious activity detected", "User requested log out everywhere"],
    )

    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "reason": "Suspicious activity detected on account",
            }
        }
    )

UserRotationResponse

Bases: BaseModel

Response schema for per-user token rotation (201 Created).

Source code in src/schemas/rotation_schemas.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
class UserRotationResponse(BaseModel):
    """Response schema for per-user token rotation (201 Created)."""

    user_id: UUID = Field(
        ...,
        description="User whose tokens were rotated",
    )
    previous_version: int = Field(
        ...,
        description="Previous user minimum token version",
    )
    new_version: int = Field(
        ...,
        description="New user minimum token version",
    )
    message: str = Field(
        default="User token rotation triggered successfully",
        description="Success message",
    )

SecurityConfigResponse

Bases: BaseModel

Response schema for security configuration.

GET /api/v1/admin/security/config Returns: 200 OK

Source code in src/schemas/rotation_schemas.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
class SecurityConfigResponse(BaseModel):
    """Response schema for security configuration.

    GET /api/v1/admin/security/config
    Returns: 200 OK
    """

    global_min_token_version: int = Field(
        ...,
        description="Current global minimum token version",
    )
    grace_period_seconds: int = Field(
        ...,
        description="Grace period for token rotation (seconds)",
    )
    last_rotation_at: str | None = Field(
        None,
        description="ISO timestamp of last global rotation (null if never)",
    )
    last_rotation_reason: str | None = Field(
        None,
        description="Reason for last global rotation (null if never)",
    )