FLEXBridge Authentication Protocols and Other Information

FLEXBridge FLEXBridge FLEXBridge Authentication Protocols and Other Information

  1. Introduction to FLEXBridge and This Document

FLEXBridge is a RESTful web service that uses JSON format. This document outlines the authentication protocols FLEXBridge supports, along with additional details about its services and processes.

  • Applicable FLEX Releases: This documentation is relevant for FLEX Releases 8.03 and up.
  • Document Revisions (as of March 2023):
    • Document name changed from “Core System API” to “Bridge Authentication Protocols” to better reflect its purpose.
    • “Secure Authentication header” renamed to “HMAC Authentication Method”.
    • FLEXBridge functions moved to the Appendix section, referencing current bridge services and functions.
    • FLEXBridge Implementation Flow Chart added.
    • Date format adjusted for bridge date responses from MM/DD/YYYY to MM/dd/yyyy.
    • All accepted date formats in bridge requests added.
    • OAuth2 Method for bridge requests added.

  1. FLEXBridge System Information

The FLEXBridge system operates on a Linux server dedicated to housing the credit union’s bridge services.

  • Server Location: The server may be on-site at the credit union or hosted by FLEX.
  • Hardware/Devices: Credit unions must procure any additional devices or hardware required by vendors for implementation projects.
  • Licensing: Credit unions must purchase FLEXBridge and vendor licensing from their FLEX Marketing Representative before any project implementations.
  • Server Setup Time: The setup of a client’s bridge server typically averages 3 to 6 weeks after FLEX receives client approval and security deposit. This timeframe should be factored into project schedules if the server is not already implemented.
  • HTTPS Methods Used: FLEXBridge’s API services primarily use the following HTTPS Methods:
    • GET
    • POST
    • PATCH (currently used only in Card Processing API)
  • Secure Communication: FLEXBridge uses HTTPS in conjunction with all service URL requests. An example request URL format is https://example.com/api/{API_SERVICE_URL_PATH}.
  • Date Formats:
    • Accepted in JSON Request body attributes: MM/dd/yyyy, MM-dd-yyyy, and yyyy-MM-dd.
    • Service Response Date Format: MM/dd/yyyy.
  • FLEX Upgrades and Credit Union Responsibilities:
    • Credit unions are responsible for notifying and providing their bridge partners with updated bridge documentation in a timely manner before setting an upgrade date.
    • Credit unions must also inform the FLEX Upgrade Team if they have FLEXBridge services implemented and which vendors are currently using them.
    • Credit unions and their bridge partners should review the Revisions section of documentation to determine if any changes will create potential issues during an upgrade.
    • FLEX strives to ensure backward compatibility of all attributes, objects, and bridge functions to maintain efficiency and utility, insulating the bridge from core upgrades.
    • After an upgrade, credit unions should review all processes and data exports as neither FLEX nor their bridge partner will know if any data is missing.

  1. FLEXBridge Authentication Protocols

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

  • 3.1. OAuth 2.0 Method The OAuth2 bridge request method requires a generated token and client authentication headers for successful data retrieval and posting to client bridge services.

    • Step One: Generate an access_token

      • Action: Run the login endpoint.

      • Request Header:

        • Content-Type: Required, indicates media type of resource; FLEX’s API uses application/json.
      • OAuth2 JSON Request Body Attributes:

        • username (String): FLEX assigned Credit Union ID (max 3 characters), Required.
        • password (String): FLEX generated password unique to each credit union, Required.
      • Example JSON Request Body:

{

  “username”: “fb1”,

  “password”: “1234567891234567891234”

}


  • Method: POST.

  • REST URL: https://{URL_ADDRESS}/olaf/login.

  • OAuth2 Login Response:

    • access_token (String): The access token value for OAuth2 requests.
    • Token Expiration: The token can be used for up to five minutes before it expires and needs to be regenerated.
    • Example Response: {“access_token”:”eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJGQjEiLCJleHAiOjE2NzkzMzE1MzB9.zDLFusf37NPcnzSe8FIfIcMX1cnY0p_bc20lUqncPODcmmW6Er93XezN0KppC8M1-SSlK3hSFi0OA5GkWdbSVA”}.
    • For Postman setup, the access_token can be set as an environment variable.
  • Step Two: Use the access_token to Perform a Request

    • Headers for OAuth2 Request Method:
      • Content-Type: Required, application/json.
      • X-FlexBridge-ClientID: Required, User ID identifying the third-party client, uniquely defined by FLEX.
      • X-FlexBridge-FIID: Required, Unique Credit Union ID defined by FLEX (alphanumeric, all lowercase for alpha characters).
      • X-FlexBridge-TestModeType: Required, Determines the environment (valid options: production, training, or test).
      • Authorization: Required, OAuth2 Token or access_token value, valid for up to five minutes.
    • Postman OAuth2 Request Example: Includes setting login endpoint headers, JSON body, and using the access token in request headers.
  • 3.2. HMAC Authentication Method HMAC Authentication utilizes an HMAC-SHA-256 algorithm, a secret key assigned by FLEX, and a combination of custom HTTPS headers.

    • Key Information:
      • Authentication Key (secret key): Provided by FLEX, alphanumeric, and unique to each vendor.
      • Client-assigned Id code (FIID): Provided by FLEX for a credit union.
      • Case-Sensitivity: The validation of the HMAC is not case-sensitive.
      • GET vs. POST Hashes: GET hashes use Query Parameters with HMAC validation, whereas POST options do not.
    • Required Headers for HMAC Authentication:
      • SALT: Required, a randomly generated ASCII string.
        • Rejection Policy: SALT values may not be reused for 60 seconds; any reuse within this period will be rejected.
      • TIMESTAMP: Required, the current UNIX time in milliseconds.
        • System Clock Synchronization: Your system clock must be synchronized with an accurate Internet time service, as requests older than 60 seconds will be rejected.
    • Calculating an HMAC:
      • Components for GET Request Hash: SALT + TIMESTAMP + URL PATH + QUERY PARAMETERS + SECRET KEY.
      • Components for POST Request Hash: SALT + TIMESTAMP + URL PATH + SECRET KEY.
      • Testing Aid: FLEX provides generic values for Authentication Key, URL_PATH, SALT, and TimeStamp to help test HMAC calculations.
        • GET Example: Authentication Key: 1234567890abcdef, URL_PATH: /api/account/search/accountnumber?query=259800, SALT: 0565f00f8fb5d8cf2e9146f71e19b326082fb30957dac7d6cb5eb81f8bb2b26b, TimeStamp: 1681340818769. Expected HMAC value: 0F5CBC85D10EB73BC6288CD36BF7A77C1143530248CFAC67D08985BD5EAAA256.
        • POST Example: Authentication Key: 1234567890abcdef, URL_PATH: /api/loans/createloan?tellerID=09&workstation=QT, SALT: 0565f00f8fb5d8cf2e9146f71e19b326082fb30957dac7d6cb5eb81f8bb2b26b, TimeStamp: 1681340818769. Expected HMAC value: 224407FFF68E73DAFE094E26C16CE9FDBCC917DD61951CBDC297C51511267E35.
      • UrlPath and QueryParameters:
        • urlPath: Indicates the endpoint and function; always starts with /api/.
        • queryParameters: Additional parameters preceded by ? to refine data.
        • Examples: /api/account/search/lastfourtaxid?query=8654 (GET), /api/loans/createloan?tellerID=77&workstation=QP (POST).
      • Code Examples for Calculating HMAC:
        • Java Example: Includes main method, calculateHmac function, toHexString, toByteArray, and generateRandomSalt.
        • C# Example: Includes Main method, HashHMACHex, HashHMAC, StringEncode, HashEncode, HexDecode, and getCurrentUnixTimestampMillis.
    • HMAC Request Headers:
      • Content-Type: Required, application/json.
      • X-FlexBridge-Salt: Required, hex-formatted ASCII string used for HMAC generation.
      • X-FlexBridge-TimeStamp: Required, UNIX timestamp in milliseconds when 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, uniquely defined by FLEX.
      • X-FlexBridge-FIID: Required, Unique Credit Union ID defined by FLEX.
      • X-FlexBridge-TestModeType: Required, Determines the environment (production, training, or test).
      • Important Note: The HMAC must be calculated before the URL escapes.
    • Postman HMAC Request Example: Provides details on setting up request headers, JSON body, and pre-request scripts for generating SALT, TIMESTAMP, and HMAC.

  1. Health Checks and Authentication Tests

These endpoints are crucial for verifying the operational status and connectivity of FLEXBridge services.

  • 4.1. Gateway Health Check

    • Purpose: Used to validate that the bridge gateway is running and ready for vendor requests.
    • Usage: The endpoint can be pasted into a web browser for testing by credit unions or third-party vendors.
    • Method: GET.
    • REST URL: https://{URL_ADDRESS}/health.
    • Examples: https://10.201.0.18/health, https://cmcfb.flexcutech.com/health.
    • Response Examples:
      • Gateway service is running.
      • Error Responses: 502 Bad Gateway or other connection messages may indicate client bridge services are down, ISP issues, or a power outage.

  • 4.2. Authentication Test

    • Purpose: Used to test authentication and validate that the credit union’s bridge services are up and running.
    • Usage: The endpoint can be used in a web browser. It may result in an error message due to missing request headers, but this still validates that services are running.
    • Method: GET.
    • REST URL: https://{URL_ADDRESS}/api/testauthentication.
    • Examples: https://216.000.117.004/api/testauthentication, https://cmcfb.flexcutech.com/testauthentication.
    • Test Authentication Response:
      • Successful Response Example: {“success”: true}.
      • Expected Error for Missing Headers: Missing required HTTP Headers (/api/testauthentication): [X-FlexBridge-Salt, X-FlexBridge-TimeStamp, X-FlexBridge-HMAC, X-FlexBridge-ClientID, X-FlexBridge-FIID].
      • Other error messages will indicate which specific request headers are missing.

  1. HTTP Status Codes Response From FLEXBridge or API Services

FLEX actively uses specific HTTP Status Codes to communicate the outcome of API requests:

  • 200 – Success

    • Description: Indicates a successful GET or POST request.
    • Example Response: { accounts:[…] }.
  • 400 – Bad Request

    • Description: Typically related to client-side issues or connections involving required headers (e.g., 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

    • Description: 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

    • Description: FLEX has added additional message information to the 500 HTTP Status Code whenever possible to help credit unions and partners resolve errors without FLEX involvement.
    • Purpose of Additional Messaging: Most messages are validation checks to ensure data accuracy or adherence to FLEX minimum requirements.
    • Resolution: Once the issue is corrected (e.g., database settings adjusted, bad data fixed), the export or request can be retried.
    • Example Error Response: {“message”: “Internal server error – …”}.
    • Common 500 Error Messages:
      • “message”: “Internal server error – Error parsing request” (likely bad data).
      • “message”: “Internal server error – Loan Distributions do not match the loan amount.”.
      • “message”: “Internal server error – Member on Do Not Allow list. Unable to open loan.”.
      • “message”: “Internal server error – A loan for an Account: 2261147 suffix: 99 Already Exists.”.
      • “message”: “Internal server error – No available suffix for the Share Type NC.”.
      • Service Unavailable/Not Deployed Messages: Occur when an API service is unavailable or hasn’t been deployed to the client’s bridge services. Examples include “IAccountService service was not found”, “ICardService service was not found”, “ILoanService service was not found”.
  • 502 – Bad Gateway

    • Description: Occurs when the FLEXBridge Gateway service is not up and running.
    • Resolution: Credit union needs to notify FLEX to restart the process.
  • 503 – Service Unavailable Error

    • Description: Occurs when the FLEXBridge service is not up and running.
    • Resolution: Credit union needs to notify FLEX to restart the process.
  • 504 – Gateway Time-out

    • Description: Occurs when the FLEXBridge Gateway service cannot receive a timely response from the credit union’s core system to complete a request. This is usually temporary due to high traffic and self-corrects.
    • Resolution: Retry the request.
  • Other Messages:

    • Gateway could not find a service implementing the endpoint:
      • Description: Indicates that the client’s bridge service is unavailable or the service has not been deployed to the server.
      • Resolution: FLEX would need to restart the client’s bridge service or deploy the missing service.

  1. Appendix: Current API Services

This section provides a quick reference to the current bridge services and functions available for credit unions with a FLEXBridge server. For more detailed information, refer to each service’s specific documentation.

  • Current API Services List:

    • Account Inquiry
    • Account Management
    • ATM (used with ITM integrations)
    • Card Processing
    • Certificate
    • Document
    • Internet Banking
    • Loan Processing
    • Share (secondary suffixes)
    • Stop Payment
    • Transactions
  • API Service Information (Detailed Functions):

    • Account Inquiry API Service: Retrieves member account information.

      • Search Methods: Name, Tax ID, Account number, Partial name, Last four digits of Tax ID, Last name and first initial.
      • Other Functions:
        • Review member account information (share, certificate, loan suffix, authorized signers, beneficiaries, co-borrowers, joint owners).
        • Review Member Account Holds.
        • Review Member Share Overdraft Information.
        • Review Member Account Notes.
        • View Member Transaction History.
        • Retrieve Member Data Records.
        • Retrieve all New Account Numbers Opened.
        • Reset a Member Audio Pin.
        • Audio Pin Validation.
    • Account Management API Service: Used to open new Member accounts.

      • Key Functionality: Includes objects and attributes for defining information regarding primary account holders, joint owners, authorized signers, and beneficiaries. It also creates the account’s primary or base share suffix.
      • Available Functions:
        • Open Pending Account: Creates a pending member account for credit union completion via FLEX system.
        • Open New Member Account: Automatically creates a new member account and base share in the credit union’s database.
    • ATM API Service: Processes transactions to Member accounts using an account or card number.

      • Transactions: Deposit, withdrawal, transfer, or loan payment by account or card number.
      • Reversals: Reversing transaction options for each of the above.
      • Modifying Transactions: Used for partial transaction reversals by account or card number.
    • Card Processing API Service: Contains data elements for member debit and credit card information.

      • Key Functionality: Allows adding (debit and credit), maintaining, or reissuing cards.
      • Available Functions:
        • Search for a card by account or card number.
        • Add a new card.
        • Update an existing card (Reissue, Block card, Change a PIN).
    • Certificate API Service: Contains data elements for adding a new Certificate of Deposit to an existing member’s account.

      • Available Functions:
        • Retrieve the next available suffix for a certificate of deposit.
        • Retrieve certificate type default information.
        • Open Certificate of Deposit.
    • Document API Service: Stores, searches, and retrieves documents from the document database.

      • Document Format: All documents stored within the FLEX system are in PDF format.
      • Data Format: All file retrieval and storing is in Binary data format.
      • Available Functions:
        • Store document.
        • Search document.
        • Retrieve document.
    • Internet Banking API Service: Represents the portion of FLEXBridge containing processes for retrieving and updating an Internet Banking profile.

      • Available Functions:
        • Retrieve profile by Tax ID (displays all linked profiles).
        • Retrieve profile by Tax ID and account number.
        • Retrieve profile by username.
        • Create an Internet Banking profile.
        • Reactivate disabled account.
        • Clear Member high-risk security options (requires re-enrollment).
        • Reactivate profile and reset high-risk security (forces re-enrollment).
        • Add new security contact to profile (existing contacts can be retrieved first).
        • Reset account authentication when username or password forgotten (requires re-enrollment).
        • Replace an Internet Banking profile password.
    • Loan Processing API Service: Allows for creating and funding new loans. Refinancing or add-on loans are not currently supported.

      • Supported Loan Types: Consumer, HELOC, mortgage, credit card, auto, lines of credit, shared secured, and other types as documented.
      • Additional Features:
        • Distributions to member share accounts.
        • Loan payoffs currently in service on the FLEX System.
        • Distribution checks.
        • Transfers directly to the credit union’s FLEX accounting system.
        • Collateral Features: Co-Borrowers, shares, vehicles, real estate, and other miscellaneous forms of collateral.
        • Origination Service Provider Options: Variable rate information, amortized fees, automatic transfers, and payroll deduction for loan payments.
      • Available Functions:
        • Retrieval of the next available loan suffix: Used before loan funding to query for a member’s next available loan type suffix.
        • Create Loan: Writes loan data as a pending (or in-process) loan requiring the credit union to complete funding, allowing for additional data collection and form printing in FLEX.
        • Post Loan: Writes a loan directly into the credit union’s database.
    • Share API Service: Allows for opening new secondary share suffixes or closing existing suffixes.

      • Available Functions:
        • Open share suffix.
        • Close share suffix.
    • Stop Payment API Service: Allows for retrieving or creating stop payments on member accounts.

      • Available Functions:
        • Retrieve stop payment for an account.
        • Create stop payment for an account.
    • Transaction API Service: Allows for member account transfers and check withdrawals.

      • Included Functions: Loan payments, savings funds transfers, and member across-account transfers.
      • Limitations: Does not allow transfers from/to a general ledger to a member account, between general ledgers, or sending transfers to locations outside the credit union’s FLEX core system.
      • Available Functions:
        • Post account transfers: Payments, transfer funds between member accounts or share suffixes.
        • Check withdrawals.

  1. Other Resources

The document references external resources for further understanding of underlying technologies:

  • HMAC: Wikipedia page on hash-based message authentication code.
  • OAuth: Wikipedia page for Open Authorization.
  • REST: Wikipedia page on RESTful services.
  • JSON: json.org JSON interchange format reference.
  • HTTP Status Codes: List of HTTP Status Code meanings.
  • Media Type: https://en.wikipedia.org/wiki/Media_type.