Authentication

The REST API uses OAuth2 bearer tokens — specifically, JWTs generated in the FFIEC Central Data Repository’s Public Web Service (PWS) portal. The token is not your CDR login password. Token lifetime is 90 days; regeneration is manual.

Creating a CDR account

1. Register at cdr.ffiec.gov/public/PWS/CreateAccount.aspx?PWS=true.
2. The FFIEC registration creates a Microsoft Entra ID identity for you — no separate Microsoft account is needed.
3. Accept the invitation email from invites@microsoft.com.
4. If the Microsoft callback link fails (it often does), go directly to cdr.ffiec.gov/public/PWS/PublicLogin.aspx and log in there.

Generating a JWT token

1. Log into cdr.ffiec.gov/public/PWS/PublicLogin.aspx.
2. Go to Account Details.
3. Generate a new JWT token.
4. Copy the full token. Valid JWTs start with ey and end with ..

A fresh token is valid for 90 days. The library considers it effectively expired when it expires within the next 24 hours.

Using the token in code

from ffiec_data_connect import OAuth2Credentials

creds = OAuth2Credentials(
    username="your_cdr_username",
    bearer_token="eyJhbGci...",  # paste the full JWT
)

token_expires is auto-detected from the JWT’s own payload — you don’t set it manually. As of 3.0.0, passing token_expires=... emits a DeprecationWarning and the value is ignored; the JWT’s exp claim is authoritative.

Check status before a long job:

if creds.is_expired:
    raise SystemExit("Token is expired (or expires within 24 hours). Regenerate.")

Recommended: environment variables

Never commit tokens to source control. A token is a 90-day credential to your CDR account; leakage is real.

import os
from ffiec_data_connect import OAuth2Credentials

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

Setting a renewal reminder

Tokens don’t auto-renew. Put a calendar reminder at day 85 of the token’s lifetime — that leaves enough buffer to regenerate, redeploy, and notice if the portal is down.

Token format — gotchas

Symptom	Likely cause
”Bearer token appears invalid (too short)“	Partial paste — copy the whole string
”JWT token must start with ‘ey’ and end with ’.’”	Copied a login password, not a JWT
CredentialError on first call	Token expired, or pasted your CDR password

Reference links

• CDR Help Desk — for account and portal issues.
• FAQs
• “What’s New” at the CDR
• Official REST API specifications (PDF) — CDR-PDD-SIS-611 v1.10.
• Reverse-engineered OpenAPI spec — unofficial, validated against live API.

Next step

Quickstart — first data pull.