FLEXBridge Authentication Protocols and Other Information

FLEXBridge 2025 FLEXBridge API Documents FLEXBridge Authentication Protocols and Other Information

This document outlines the authentication protocols and additional information regarding FLEXBridge, its services, and processes within the www.flexcutech.com system. FLEXBridge is a RESTful web service that utilizes JSON format for data exchange.

Available FLEX Releases: 8.05 and up.

1. FLEXBridge Information

  • Server Environment:
    • The bridge system operates on a Linux server dedicated to housing the credit union’s bridge services.
    • Credit unions are responsible for procuring any additional hardware or devices required by vendors for implementation projects.
    • Each FLEX credit union will have its bridge services server, which can be on-site or hosted by FLEX.
  • Licensing:
    • Credit unions must purchase FLEXBridge and vendor licensing from their FLEX Marketing Representative before project implementations.
  • Server Setup Time:
    • Bridge server setup typically takes 3 to 6 weeks after FLEX receives client approval and a security deposit. This timeframe should be factored into project schedules.
  • HTTPS Methods:
    • FLEXBridge’s API services primarily use the following HTTPS methods:
      • GET
      • POST
      • PATCH (currently used only in Card Processing API)
    • All service URL requests use HTTPS (e.g., https://example.com/api/{API_SERVICE_URL_PATH}).
  • Date Formats:
    • Accepted in JSON Request Body: MM/dd/yyyy, MM-dd-yyyy, and yyyy-MM-dd.
    • Bridge Service Response Format: MM/dd/yyyy.
  • FLEX Upgrades:
    • Credit unions are responsible for:
      • Notifying and providing bridge partners with updated bridge documentation in a timely manner before an upgrade date.
      • Informing the FLEX Upgrade Team about implemented FLEXBridge services and current vendors.
    • Review the “Revisions” section of bridge services documentation with bridge partners to identify potential issues from changes.
    • FLEX aims for backward compatibility of attributes, objects, and functions to ensure efficiency and utility, insulating the bridge from core upgrades.
    • Review all processes and data exports after an upgrade to check for missing data.

2. Bridge Connection and Flow Chart

The FLEXBridge architecture involves the following components:

  • 3rd Party: Connects to the Public IP of the FLEXBridge/Web server as an API interface.
  • Firewall: Segregates the FLEXBridge/Web, App Server, and IBM Server into separate networks.
  • Switch: Connects the 3rd party host PC and the FLEXBridge/Web server to the firewall.
  • FLEXBridge/Web Server:
    • Acts as a proxy between the 3rd party and the App Server.
    • Used to import files from the 3rd party host PC.
  • App Server:
    • Provides FLEX services.
    • Connects to data sources such as IBM Servers.
  • IBM Server: Used as the data source and back-end core for the App Server and FLEX Services.

3. Authentication Methods

FLEXBridge supports two primary authentication methods: OAuth 2.0 and HMAC Authentication.

3.1. OAuth 2.0 Method

The OAuth 2.0 method requires a generated access token and client authentication headers for successful requests.

Step One: Generate an access_token

  • Method: POST
  • REST URL: https://{URL_ADDRESS}/olaf/login
  • OAuth2 Login Request Header:
    • Content-Type: application/json (Required) – Indicates the media type for the request.
  • OAuth2 JSON Request Body Attributes:
    • username (String, Required): FLEX-assigned Credit Union ID (maximum 3 characters).
    • password (String, Required): FLEX-generated password unique to each credit union.
  • OAuth2 JSON Request Body Example:
    {
      “username”: “fb1”,
      “password”: “1234567891234567891234”
    }

  • OAuth2 Login Response Attribute:
    • access_token (String): The access token value for OAuth2 requests. It is valid for up to five minutes before expiration, after which it must be regenerated.
  • OAuth2 Login Response Example:
    {“access_token”:”eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJGQjEiLCJleHAiOjE2NzkzMzE1MzB9.zDLFusf37NPcnzSe8FIfIcMX1cnY0p_bc20lUqncPODcmmW6Er93XezN0KppC8M1-SSIK3hSFI0OA5GkWdbSVA”}

Step Two: Use the access_token to Perform a Request

  • Headers for OAuth2 Request Method:
    • Content-Type (Required): application/json – Indicates the content type for the request.
    • X-FlexBridge-ClientID (Required): User ID identifying the third-party client, defined by FLEX as a unique ID.
    • X-FlexBridge-FIID (Required): Unique Credit Union ID defined by FLEX (alphanumeric, all alpha characters must be lowercase).
    • X-FlexBridge-TestModeType (Required): Determines the environment for HTTPS Method calls. Valid options: production, training, or test.
    • Authorization (Required): OAuth2 Token or “access token” value, valid for up to five minutes.

3.2. HMAC Authentication Method

HMAC Authentication uses HMAC-SHA-256 with an assigned secret key and custom HTTPS headers.

  • Authentication Key: FLEX provides an alphanumeric, unique secret key for each vendor.
  • Validation: HMAC validation is not case-sensitive.
  • HMAC Calculation Data:
    • GET Request: SALT + TIMESTAMP + URL PATH + QUERY PARAMETERS + SECRET KEY
    • JSON POST Request: SALT + TIMESTAMP + URL PATH + SECRET KEY
  • SALT and TIMESTAMP:
    • SALT: A randomly generated ASCII string, sent as an HTTPS header. Must not be reused for 60 seconds.
    • TIMESTAMP: Current UNIX time in milliseconds, sent as an HTTPS header. Your system clock must be synchronized with an accurate Internet time service, as requests older than 60 seconds will be rejected.
  • HMAC Request Headers:
    • Content-Type (Required): application/json – Indicates the media type of the resource.
    • X-FlexBridge-Salt (Required): The hex-formatted ASCII SALT value used for HMAC generation.
    • X-FlexBridge-TimeStamp (Required): UNIX timestamp value (in milliseconds) when the request was submitted.
    • X-FlexBridge-HMAC (Required): HMAC-SHA-256 value calculated by hashing SALT + URL PATH + TIMESTAMP + SECRET KEY.
    • X-FlexBridge-ClientID (Required): Client ID identifying the vendor submitting the request, a unique ID defined by FLEX.
    • X-FlexBridge-FIID (Required): Unique Credit Union ID defined by FLEX.
    • X-FlexBridge-TestModeType (Required): Determines the environment for HTTPS Method calls. Valid options: production, training, or test.
  • Important Note: The HMAC must be calculated before the URL escapes.

4. Gateway Health Check

The Health Check endpoint verifies that the bridge gateway is running and ready for vendor requests.

  • Method: GET
  • REST URL: https://{URL_ADDRESS}/health
  • Expected Response: Gateway service is running
  • Troubleshooting: A 502 Bad Gateway or other connection messages indicate that client bridge services are down, experiencing ISP issues, or a power outage.

5. Authentication Test

The test authentication endpoint validates authentication and confirms that the credit union’s bridge services are operational.

  • Method: GET
  • REST URL: https://{URL_ADDRESS}/api/testauthentication
  • Expected Response (Success):
    {
      “success”: true
    }

  • Expected Response (Missing Headers): A web browser test may yield a message like: Missing required HTTP Headers (/api/testauthentication): [X-FlexBridge-Salt, X-FlexBridge-TimeStamp, X-FlexBridge-HMAC, X-FlexBridge-ClientID, X-FlexBridge-FIID]. This message still validates that the bridge services are running.

6. HTTP Status Codes Response From FLEXBridge or API Services

FLEXBridge actively uses the following HTTP Status Codes:

  • 200 Success: Indicates a successful GET or POST request.
    • Example Response:
      {
        “accounts”: […]
      }

  • 400 Bad Request:
    • Usually related to client errors or issues with required headers (X-FlexBridge-Salt, X-FlexBridge-TimeStamp, X-FlexBridge-HMAC, X-FlexBridge-FIID, X-FlexBridge-ClientID), or invalid HMAC information.
    • Example Error Response:
      {
        “error_message”: “Invalid HMAC: Invalid HMAC provided”
      }

  • 404 Not Found:
    • Occurs when the URL used is not mapped or recognized by the FLEXBridge Service.
    • Example Error Response:
      {
        “error”: “HTTP 404 Not Found”
      }

  • 500 Internal Server Error:
    • Indicates a server-side error. FLEX provides additional message information to aid in troubleshooting without FLEX involvement.
    • Messages may require the credit union to adjust database settings or change data in the export.
    • Example Error Response:
      {
        “message”: “Internal server error – …”
      }

    • Other Potential 500 Error Messages: May indicate that a service is unavailable or has not been deployed to the client’s bridge services (e.g., IAccountService service was not found).
  • 502 Bad Gateway:
    • Occurs when the FLEXBridge Gateway service is not running. Contact FLEX to restart the process.
  • 503 Service Unavailable Error:
    • Occurs when the FLEXBridge service is not running. Contact FLEX to restart the process.
  • 504 Gateway Time-out:
    • Occurs when the FLEXBridge Gateway service does not receive a timely response from the credit union’s core system. This is usually temporary; retry the request.

7. Appendix: Current API Services

This section provides a quick reference guide to current bridge services and functions. Refer to individual service documentation for more detailed information.

  • Account Inquiry: Retrieves member account information (by Name, Tax ID, Account number, etc.), displays suffix information, lists authorized signers/beneficiaries/joint owners, reviews holds/overdrafts/notes, views transaction history, retrieves data records, retrieves new account numbers, and manages Audio PINs.
  • Account Management: Opens new member accounts, including pending accounts and automatically creating new member accounts and base shares.
  • ATM: Processes transactions (deposit, withdrawal, transfer, loan payment) to member accounts using account or card numbers, including reversals and modifications.
  • Card Processing: Manages member debit and credit card information (add, update, reissue, block, change PIN).
  • Certificate: Manages Certificates of Deposit (retrieve next available suffix, retrieve default information, open Certificate of Deposit).
  • Document: Stores, searches, and retrieves documents (in PDF format, binary data transfer) from the document database.
  • Internet Banking: Retrieves and updates Internet Banking profiles, reactivates disabled accounts, clears high-risk security options, adds new security contacts, and resets account authentication/passwords.
  • Loan Processing: Creates and funds new loans (consumer, HELOC, mortgage, credit card, auto, lines of credit, shared secured, etc.), supports distributions to share accounts, loan payoffs, distribution checks, and transfers to FLEX accounting. Includes collateral features and options for variable rates, amortized fees, automatic transfers, and payroll deduction.
  • Share: Opens new secondary share suffixes or closes existing ones.
  • Stop Payment: Retrieves or creates stop payments on member accounts.
  • Transaction: Allows member account transfers and check withdrawals, including loan payments, savings funds transfers, and inter-member account transfers. Does not support transfers to/from general ledgers or outside the FLEX core system.