Credentials

Two credential classes are exported. Only one is usable.

OAuth2Credentials

from ffiec_data_connect import OAuth2Credentials

OAuth2Credentials(
    username: str,
    bearer_token: str,
    # token_expires: datetime | None = None,   # deprecated in 3.0.0 — do not pass
)

Immutable container for a FFIEC username and a 90-day JWT bearer token. This is the credential type accepted by every collect_* function, the AsyncCompatibleClient, and create_protocol_adapter.

Parameters

Parameter	Type	Description
username	str	FFIEC PWS username. Sent in the UserID header.
bearer_token	str	JWT bearer token from the CDR portal. Must start with ey, end with ., and be longer than 16 characters.
token_expires	datetime	Deprecated in 3.0.0. Passing a value emits DeprecationWarning and is ignored — expiry is always decoded from the JWT’s exp claim. Drop this argument from your call.

The constructor validates the token shape (ey..., trailing .) and strips whitespace from both fields. Passing empty values raises CredentialError.

Both username and bearer_token are stored as private attributes and exposed via read-only properties. __setattr__ blocks mutation of public attributes after __init__ returns — you cannot hot-swap a token on an existing instance; construct a new one.

Security warning

If you pass bearer_token as a string literal and the FFIEC_BEARER_TOKEN environment variable is unset, the constructor issues a UserWarning nudging you toward the env-var form:

import os
from ffiec_data_connect import OAuth2Credentials

creds = OAuth2Credentials(
    username=os.environ["FFIEC_USERNAME"],
    bearer_token=os.environ["FFIEC_BEARER_TOKEN"],
)

See Authentication for the full recommended setup.

Properties

Property	Type	Notes
username	str	Stripped username.
bearer_token	str	Raw JWT.
token_expires	datetime | None	JWT-extracted expiry (always — the deprecated token_expires init argument is ignored).
is_expired	bool	True if token_expires is within 24 hours of now.
credential_source	CredentialType	Always CredentialType.SET_FROM_INIT for this class.

Methods

• get_auth_headers() -> dict[str, str] — returns the headers actually sent to the REST API. Useful if you are hand-rolling requests against the FFIEC endpoint outside the collect_* layer.

  creds.get_auth_headers()
  # {
  #   "UserID": "your_ffiec_username",
  #   "Authentication": "Bearer eyJ...",
  #   "Content-Type": "application/json",
  #   "Accept": "application/json",
  # }

  Note: the header is Authentication, not Authorization — this is FFIEC’s quirk, not a typo.

• test_credentials() -> bool — local-only validation. Checks token shape and expiry; it does NOT make a live API call and emits a UserWarning saying so. A True return guarantees nothing about server acceptance. To actually verify end-to-end, call collect_reporting_periods.

  The session=… keyword this method used to accept is deprecated as of 3.0.0 — it was a SOAP-era stub and has no effect in the REST path. Passing any value emits a DeprecationWarning; drop the argument.

JWT expiry auto-extraction

FFIEC tokens are unsigned (alg: "none"), so the library base64-decodes the payload segment without crypto and reads the exp claim. If decoding fails or the claim is absent, token_expires stays None and is_expired returns False. This is intentional — missing expiry is treated as “don’t know, trust the user.”

__str__ / __repr__

Both mask the username and token to first+last character with asterisks in between. Safe to log:

>>> print(creds)
OAuth2Credentials(username='j******e', token='e****.', expires_in='47 days')

CredentialType

from ffiec_data_connect import CredentialType

CredentialType.NO_CREDENTIALS   # 0
CredentialType.SET_FROM_INIT    # 1
CredentialType.SET_FROM_ENV     # 2

Enum used by the credential_source attribute. Retained mostly for symmetry with the v2 API; OAuth2Credentials always reports SET_FROM_INIT.

WebserviceCredentials (deprecated)

from ffiec_data_connect import WebserviceCredentials

The v2 SOAP credential class. In v3.0.0 the constructor unconditionally raises SOAPDeprecationError with a message pointing you at OAuth2Credentials. It exists only so that v2-era code fails loudly rather than silently. There is no way to make it usable; migrate.

>>> WebserviceCredentials(username="u", password="p")
Traceback (most recent call last):
  ...
ffiec_data_connect.exceptions.SOAPDeprecationError:
======================================================================
FFIEC SOAP API DISCONTINUED
======================================================================
...

See Migration from v2 for the full walkthrough.

See also

• Authentication — how to get the JWT, env-var setup, token rotation.
• Functions § credential argument — how collect_* accepts credentials (new style vs deprecated old style).
• Upstream credentials.py.