Lists

Instance (jam.Jam)¶

Config¶

[jam.jose.jwt.list]
type = "black"
backend = "redis"
redis_uri = "redis://localhost:6379"
ttl = 3600

Args:

type: str - List type: black or white.
backend: str - Storage backend: redis, json, memory.
redis_uri: str - Redis connection URI (for redis backend).
json_path: str - JSON file path (for json backend).
ttl: int - Time to live in seconds (optional, for redis).
prefix: str - Key prefix for namespacing.

Usage¶

from jam import Jam

jam = Jam(config="config.toml")

Add token to list¶

Method: jam.jwt_list.add

Adds token to blacklist or whitelist.

Args:

token: str - JWT token to add.

jam.jwt_list.add(token=token)

Check token in list¶

Method: jam.jwt_list.check

Checks if token is in list.

Args:

token: str - JWT token to check.

Returns:

bool: True if token is in list, False otherwise.

is_revoked = jam.jwt_list.check(token=token)
if is_revoked:
    print("Token is revoked")

Delete token from list¶

Method: jam.jwt_list.delete

Removes token from list.

Args:

token: str - JWT token to delete.

jam.jwt_list.delete(token=token)

Add multiple tokens¶

Method: jam.jwt_list.add_many

Adds multiple tokens to list.

Args:

tokens: list[str] - List of JWT tokens.

jam.jwt_list.add_many(tokens=[token1, token2, token3])

Check multiple tokens¶

Method: jam.jwt_list.check_many

Checks multiple tokens in list.

Args:

tokens: list[str] - List of JWT tokens.

Returns:

dict[str, bool]: Dict mapping tokens to their presence status.

results = jam.jwt_list.check_many(tokens=[token1, token2])
print(results)
>>> {token1: True, token2: False}

Delete multiple tokens¶

Method: jam.jwt_list.delete_many

Removes multiple tokens from list.

Args:

tokens: list[str] - List of JWT tokens.

jam.jwt_list.delete_many(tokens=[token1, token2])

Standalone (module)¶

RedisList¶

Redis-based token list. Most optimal for production with TTL support.

Module: jam.jose.lists.redis.RedisList

Args:

type: str - List type: black or white.
prefix: str - Key prefix for namespacing.
redis_uri: str - Redis connection URI.
redis: Redis - Pre-configured Redis client (optional).
ttl: int - Time to live in seconds (optional).
logger: BaseLogger - Logger instance.

from jam.jose.lists.redis import RedisList

list = RedisList(
    type="black",
    prefix="jwt",
    redis_uri="redis://localhost:6379",
    ttl=3600
)
list.add(token)
list.check(token)
list.delete(token)

MemoryList¶

In-memory token list. Simple but not persistent.

Module: jam.jose.lists.memory.MemoryList

Args:

type: str - List type: black or white.
prefix: str - Key prefix for namespacing.
logger: BaseLogger - Logger instance.

from jam.jose.lists.memory import MemoryList

list = MemoryList(
    type="black",
    prefix="jwt"
)
list.add(token)
list.check(token)
list.delete(token)

JSONList¶

JSON file-based token list. Persistent but limited scalability.

Module: jam.jose.lists.json.JSONList

Args:

type: str - List type: black or white.
prefix: str - Key prefix for namespacing.
json_path: str - Path to JSON file.
logger: BaseLogger - Logger instance.

from jam.jose.lists.json import JSONList

list = JSONList(
    type="black",
    prefix="jwt",
    json_path="blacklist.json"
)
list.add(token)
list.check(token)
list.delete(token)

Methods comparison¶

Method	MemoryList	RedisList	JSONList
`add`	✓	✓	✓
`delete`	✓	✓	✓
`check`	✓	✓	✓
`add_many`	✓	✓	✓
`delete_many`	✓	✓	✓
`check_many`	✓	✓	✓
TTL support	✗	✓	✗
Persistence	✗	✓	✓

Blacklist vs Whitelist¶

Blacklist¶

Tokens in blacklist are rejected.

list = RedisList(type="black", prefix="jwt", redis_uri="...")

# Token is in blacklist
if list.check(token):
    raise Exception("Token has been revoked")

Whitelist¶

Only tokens in whitelist are accepted.

list = RedisList(type="white", prefix="jwt", redis_uri="...")

# Token is not in whitelist
if not list.check(token):
    raise Exception("Token is not valid")