Tokens¶

bluefox_auth.tokens

JWT token creation and validation using PyJWT.

Token types¶

Type	Purpose	Default expiry
`access`	Authenticate API requests	30 minutes
`refresh`	Obtain new access tokens	7 days
`password_reset`	Reset password	1 hour
`email_verify`	Verify email address	24 hours

Token claims¶

All tokens include:

{
  "sub": "1",
  "type": "access",
  "jti": "a1b2c3d4...",
  "iat": 1700000000,
  "exp": 1700001800,
  "aud": "bluefox"
}

Functions¶

create_access_token¶

def create_access_token(user_id: int, settings: AuthSettings) -> str

create_refresh_token¶

def create_refresh_token(user_id: int, settings: AuthSettings) -> tuple[str, str, str]

Returns (token_string, jti, family_id). The family_id is a new UUID hex string for the token family.

create_rotated_refresh_token¶

def create_rotated_refresh_token(
    user_id: int, family_id: str, settings: AuthSettings
) -> tuple[str, str]

Returns (token_string, jti). Reuses the existing family_id.

create_token_pair¶

def create_token_pair(
    user_id: int, settings: AuthSettings
) -> tuple[TokenPair, str, str]

Returns (token_pair, refresh_jti, refresh_family_id).

create_special_token¶

def create_special_token(
    user_id: int,
    token_type: str,
    expire_minutes: int,
    settings: AuthSettings,
    extra_claims: dict | None = None,
) -> str

For password reset and email verification tokens. Raises ValueError if extra_claims tries to override reserved fields.

decode_token¶

def decode_token(
    token: str, settings: AuthSettings, expected_type: str
) -> TokenPayload

Decodes and validates a JWT. The expected_type parameter is required — every decode call must declare what token type it expects. Raises InvalidTokenError on any failure.

Models¶

TokenPayload¶

class TokenPayload(BaseModel):
    sub: int
    type: str
    exp: datetime
    iat: datetime
    jti: str
    audience: str

TokenPair¶

class TokenPair(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"

InvalidTokenError¶

Exception raised by decode_token for any token validation failure (expired, invalid signature, wrong type, missing claims, etc.).