# Signing With Timestamps

If you want to expire signatures you can use the `TimestampSigner` class which adds timestamp information and signs it. On unsigning you can validate that the timestamp is not older than a given age.

    from itsdangerous import TimestampSigner
    s = TimestampSigner('secret-key')
    string = s.sign('foo')

    s.unsign(string, max_age=5)
    Traceback (most recent call last):
      ...
    itsdangerous.exc.SignatureExpired: Signature age 15 > 5 seconds

class itsdangerous.timed.TimestampSigner(secret_key, salt=b'itsdangerous.Signer', sep=b'.', key_derivation=None, digest_method=None, algorithm=None)

  Works like the regular `Signer` but also records the time of the signing and can be used to expire signatures. The `unsign()` method can raise `SignatureExpired` if the unsigning failed because the signature is expired.

  Parameters:

    - secret_key (str | bytes | cabc.Iterable[str] | cabc.Iterable[bytes])

    - salt (str | bytes | None)

    - sep (bytes)

    - key_derivation (str)

    - digest_method (Any)

    - algorithm (SigningAlgorithm)

  get_timestamp()

    Returns the current timestamp. The function must return an integer.

    Return type:

      int

  timestamp_to_datetime(ts)

    Convert the timestamp from `get_timestamp()` into an aware :class`datetime.datetime` in UTC.

    Changelog

    Changed in version 2.0: The timestamp is returned as a timezone-aware `datetime` in UTC rather than a naive `datetime` assumed to be UTC.

    Parameters:

      ts (int)

    Return type:

      datetime

  sign(value)

    Signs the given string and also attaches time information.

    Parameters:

      value (str | bytes)

    Return type:

      bytes

  unsign(signed_value: str | bytes, max_age: int | None = None, return_timestamp: Literal[False] = False) → bytes
  unsign(signed_value: str | bytes, max_age: int | None = None, return_timestamp: Literal[True] = True) → tuple[bytes, datetime]

    Works like the regular `Signer.unsign()` but can also validate the time. See the base docstring of the class for the general behavior. If `return_timestamp` is `True` the timestamp of the signature will be returned as an aware `datetime.datetime` object in UTC.

    Changelog

    Changed in version 2.0: The timestamp is returned as a timezone-aware `datetime` in UTC rather than a naive `datetime` assumed to be UTC.

    Parameters:

      - signed_value (str | bytes)

      - max_age (int | None)

      - return_timestamp (bool)

    Return type:

      tuple[bytes, datetime] | bytes

  validate(signed_value, max_age=None)

    Only validates the given signed value. Returns `True` if the signature exists and is valid.

    Parameters:

      - signed_value (str | bytes)

      - max_age (int | None)

    Return type:

      bool

class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None = b'itsdangerous', serializer: None | _PDataSerializer[str] = None, serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None, serializer: _PDataSerializer[bytes], serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None = b'itsdangerous', *, serializer: _PDataSerializer[bytes], serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None, serializer: Any, serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)
class itsdangerous.timed.TimedSerializer(secret_key: str | bytes | Iterable[str] | Iterable[bytes], salt: str | bytes | None = b'itsdangerous', *, serializer: Any, serializer_kwargs: dict[str, Any] | None = None, signer: type[Signer] | None = None, signer_kwargs: dict[str, Any] | None = None, fallback_signers: list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]] | None = None)

  Uses `TimestampSigner` instead of the default `Signer`.

  Parameters:

    - secret_key (str | bytes | cabc.Iterable[str] | cabc.Iterable[bytes])

    - salt (str | bytes | None)

    - serializer (_PDataSerializer[_TSerialized])

    - serializer_kwargs (dict[str, Any])

    - signer (type[Signer])

    - signer_kwargs (dict[str, Any])

    - fallback_signers (list[dict[str, Any] | tuple[type[Signer], dict[str, Any]] | type[Signer]])

  default_signer

    alias of `TimestampSigner`

  iter_unsigners(salt=None)

    Iterates over all signers to be tried for unsigning. Starts with the configured signer, then constructs each signer specified in `fallback_signers`.

    Parameters:

      salt (str | bytes | None)

    Return type:

      Iterator[TimestampSigner]

  loads(s, max_age=None, return_timestamp=False, salt=None)

    Reverse of `dumps()`, raises `BadSignature` if the signature validation fails. If a `max_age` is provided it will ensure the signature is not older than that time in seconds. In case the signature is outdated, `SignatureExpired` is raised. All arguments are forwarded to the signer’s `unsign()` method.

    Parameters:

      - s (str | bytes)

      - max_age (int | None)

      - return_timestamp (bool)

      - salt (str | bytes | None)

    Return type:

      Any

  loads_unsafe(s, max_age=None, salt=None)

    Like `loads()` but without verifying the signature. This is potentially very dangerous to use depending on how your serializer works. The return value is `(signature_valid, payload)` instead of just the payload. The first item will be a boolean that indicates if the signature is valid. This function never fails.

    Use it for debugging only and if you know that your serializer module is not exploitable (for example, do not use it with a pickle serializer).

    Changelog

    Added in version 0.15.

    Parameters:

      - s (str | bytes)

      - max_age (int | None)

      - salt (str | bytes | None)

    Return type:

      tuple[bool, Any]