FFIEC Account Setup Instructions

Important

Authentication Migration Notice (Effective August 25, 2025)

The FFIEC CDR is transitioning to Microsoft Entra ID authentication with optional multifactor authentication (MFA). All users must complete a registration process to migrate their accounts to the new authentication protocol.

  • Legacy SOAP API will remain available until February 28, 2026

  • All legacy security tokens will expire on February 28, 2026

  • Users must transition to the REST API before this date

Prerequisites for ffiec_data_connect package

The ffiec_data_connect package supports two authentication methods:

1. REST API (Recommended - Modern OAuth2/JWT)

Starting August 25, 2025, the FFIEC uses JSON Web Tokens (JWT) for authentication:

  • JWT tokens begin with ey and end with .

  • Tokens expire every 90 days and must be regenerated

  • The token is NOT your account password - it must be generated separately

  • REST API specifications available at: https://cdr.ffiec.gov/public/Files/SIS611_-_Retrieve_Public_Data_via_Web_Service.pdf

2. SOAP API (Legacy - Deprecated February 28, 2026)

The legacy SOAP API remains available for backward compatibility but will be discontinued.

Account Creation and Setup

New Users

  1. Create FFIEC Account

    Note

    No separate Microsoft account required! The FFIEC registration process will create the necessary Microsoft Entra ID authentication for you.

    Warning

    Callback Link Issues

    After completing Microsoft verification, the callback link may not work properly. If you encounter an error or blank page, manually navigate to: https://cdr.ffiec.gov/public/PWS/PublicLogin.aspx

  2. Generate JWT Token

Existing Users - Migration Process

Starting August 25, 2025, existing users must migrate:

  1. Receive Migration Email

    • You’ll receive an invitation from invites@microsoft.com

    • This email contains a link to accept the migration

  2. Complete Migration

    Warning

    Callback Link Issues

    After completing Microsoft verification, the callback link may not work properly. If you encounter an error or blank page, manually navigate to: https://cdr.ffiec.gov/public/PWS/PublicLogin.aspx

  3. Generate New Token

    Warning

    After migration, you MUST generate a new JWT token. The new tokens are longer than previous tokens.

    • Log into your migrated account

    • Generate a new JWT token

    • Update your code with the new token

  4. Migration Issues

    If migration fails:

    • Try the migration process again

    • If it continues to fail, create a new account following the “New Users” process

    • Contact CDR Help Desk: cdr.help@cdr.ffiec.gov

Using Credentials in Code

REST API (JWT Token) - Recommended

from ffiec_data_connect import OAuth2Credentials
from datetime import datetime, timedelta

# JWT tokens start with 'ey' and end with '.'
# Example: eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0...YXVkIjoiUFdTIFVzZXIifQ.

creds = OAuth2Credentials(
    username="your_username",  # Your CDR account username
    bearer_token="eyJhbGci...",  # JWT token from CDR PWS portal (NOT your password!)
    token_expires=datetime.now() + timedelta(days=90)  # Tokens expire after 90 days
)

# Use with REST API (no session needed)
import ffiec_data_connect as fdc

data = fdc.collect_data(
    session=None,  # None for REST
    creds=creds,
    rssd_id="37",
    reporting_period="2024-09-30",
    series="call"
)

SOAP API (Legacy - Deprecated)

Warning

SOAP API will be discontinued on February 28, 2026. Please migrate to REST API.

from ffiec_data_connect import WebserviceCredentials, FFIECConnection

# Legacy SOAP credentials
creds = WebserviceCredentials(
    username="your_username",
    password="your_password"  # Account password (not JWT token)
)

conn = FFIECConnection()

# Use with SOAP API
import ffiec_data_connect as fdc

data = fdc.collect_data(
    session=conn,  # Connection object for SOAP
    creds=creds,
    rssd_id="37",
    reporting_period="6/30/2024",  # SOAP uses MM/DD/YYYY format
    series="call"
)

Important Notes

Caution

Common Authentication Mistakes

  1. Using password instead of JWT token: The REST API requires the JWT token generated from the portal, NOT your account password

  2. Token expiration: JWT tokens expire after 90 days - set up reminders to regenerate

  3. Token format: Valid JWT tokens always start with ey and end with .

  4. Migration required: After account migration, old tokens become invalid - generate new ones immediately

Token Management Best Practices

  • Store tokens securely (use environment variables or secret management systems)

  • Never commit tokens to version control

  • Implement token refresh logic before expiration

  • Monitor token expiration dates in production systems

Additional Resources

Tip

REST API Documentation

While the official FFIEC documentation provides the authoritative reference, we’ve created a reverse-engineered OpenAPI specification based on extensive testing. This specification:

  • Documents actual API behavior including quirks and non-standard patterns

  • Provides complete request/response schemas

  • Available at: REST API Reference

  • Raw YAML file: docs/ffiec_rest_api_openapi.yaml in the repository

Screen shot of FFIEC account creation page