API Reference — CipherToken¶

The CipherToken class is the core token engine. It handles signing, verification, decoding, rotation, and expiry inspection for both access and refresh tokens.

Constructor¶

from ciphertoken import CipherToken

token = CipherToken(
    secret: str,
    algorithm: str,
    access_ttl: int,
    refresh_ttl: int,
)

Parameter	Type	Description
`secret`	`str`	Signing key (HMAC secret or RSA/ECDSA private key in PEM)
`algorithm`	`str`	Algorithm constant from `ciphertoken.algorithms`
`access_ttl`	`int`	Access token lifetime in seconds
`refresh_ttl`	`int`	Refresh token lifetime in seconds

Properties¶

Property	Type	Description
`secret`	`str`	Masked secret (first 8 chars + `...`)
`access_ttl`	`int`	Access token TTL in seconds
`refresh_ttl`	`int`	Refresh token TTL in seconds

Synchronous Methods¶

payload(payload=None) -> str

Create a generic access token.

access(payload=None) -> str

Create an access token.

refresh(payload=None) -> str

Create a refresh token.

decode(token) -> dict

Decode and validate a token. Returns full claims. Raises ValueError if invalid.

verify(token) -> bool

Validate signature and expiry.

rotation(refresh_token, payload=None) -> Tuple[str, str]

Rotate a refresh token into a new access + refresh pair.

inspect(token) -> dict

Decode without strict signature or expiry validation. For debugging.

remaining_time(token) -> Optional[int]

Seconds until token expiry, or None.

algorithm_name() -> str

Current algorithm string (e.g., "HS256").

Asynchronous Methods¶

access_async(payload=None) -> str

Async access token generation.

refresh_async(payload=None) -> str

Async refresh token generation.

decode_async(token) -> dict

Async decode and validate.

verify_async(token) -> bool

Async verify signature and expiry.

rotation_async(refresh_token, payload=None) -> Tuple[str, str]

Async token rotation.

Helper Functions¶

Function	Signature	Description
`is_jwt_format`	`(token: str) -> bool`	Fast format check — 3 dot-separated parts
`validate_jwt_format`	`(token: str) -> bool`	Same as above, raises `ValueError` on invalid

Claims Structure¶

Every token contains:

Claim	Type	Description
`exp`	`int`	UNIX expiry timestamp
`ttl`	`int`	Time-to-live in seconds
`token`	`str`	`"access"` or `"refresh"`
`jti`	`str`	UUID v4 identifier
`payload`	`dict`	User-provided claims

Quick Lookup¶

➡️ API Index — Searchable method and constant reference