# Candescent Developer Documentation - Complete Reference > Candescent provides Digital Banking APIs, Mobile SDKs, and developer tools for financial institutions. This is the complete LLM-friendly documentation content. --- # GETTING STARTED ## API Categories Overview The Candescent Digital Banking Platform provides a comprehensive suite of APIs organized into logical categories. This guide outlines each API category, making it easier to understand their capabilities and access the detailed documentation. ## At a Glance | Category | Description | Primary Use Cases | | --- | --- | --- | | Authentication (#authentication) | OAuth token services supporting legacy v1 and current v2 flows | Create, refresh, and revoke access tokens | | Customer Management (#customer-management) | Registration state and access management, user profile and identity, and contact information | Manage registration, password resets, account unlocks, user profiles, and contact updates | | Core Banking (#core-banking) | Account data, transactions, activities, and banking images | Retrieve balances, account details, transaction history, user activity events, and check or statement images | | Business Banking (#business-banking) | Business onboarding and registration, profile overview, and entitlements | Manage business onboarding, registration status, profiles, and access control | | Money Movement (#money-movement) | Transfer recipients and payment execution | Manage recipients and perform one‑time or scheduled transfers | | Alerts And Notifications (#alerts-and-notifications) | Alert types, templates, preferences, notification channels, history and events | Configure, manage, and deliver alerts while controlling notification settings | | Documents And Preferences (#documents-and-preferences) | Institutional and user disclosures and electronic Statements | Manage disclosure creation, updates, and status and enable paperless documents | | Customer Campaigns (#customer-campaigns) | Experience groups, jobs, promotions, and audience targeting | Segment users, upload cohorts, manage promotions, and track job execution | | MX (#mx) | Transparent passthrough proxy APIs to MX Platform, Real Time, Reporting, and SSO | Aggregate external financial accounts, synchronize core data in real time, process daily MX change files, and embed MX widgets with SSO | | --- | --- | | OAuth 2.0 token issuance, refresh, and revocationSupport for Client Credentials, Password, and Authorization Code grantsLegacy OAuth V1 support for older endpointsUser and institution‑scoped authentication | Authenticate before calling any protected APIImplement login and session managementSecure third‑party or server‑to‑server integrations | OAuth V1 (/api/generated/o-auth-v-1/)OAuth V2 (/api/generated/o-auth-v-2/) | **Token Versions** - V1: Legacy endpoints (Send Event, Destinations, Get FI Customer, Register User) - V2: All modern APIs (Accounts, Alerts, Disclosures, Money Movement, Transactions) --- ## Customer Management {#customer-management} Customer Management APIs handle digital banking customer identity and access. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | Registration– Enroll customers into digital bankingAccess Management– Password reset via OTP– User unlock operationsProfile Retrieval– Name, contact info, identifiers, statusContact Info– Manage MFA and notification destinations and postal address | Register new digital banking usersDisplay or update customer profilesSupport password reset and recovery flowsRetrieve available MFA contact methods | Registration And Access (/api/generated/registration-and-access/)Profile And Status (/api/generated/profile-and-status/)Contact Info (/api/generated/contact-info/) | --- ## Core Banking {#core-banking} Core Banking APIs provide access to customer financial data including accounts, transactions, banking activities, and banking images. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | Account Information: Retrieve account balances, status, and detailed attributesTransaction History: Access posted and pending transactions with date filteringBanking Activities: Query paged, filtered banking activity events (authentication, operational, and transaction-related) over a time rangeBanking Images: Download check images, deposit slips, and statement images linked to transactionsAdvanced Filtering: OData filtering by account category (DEPOSIT, LOAN, INVESTMENT)Cross‑Account Support: View linked and cross‑user accounts in a unified experienceBalance Reconciliation: Support for running balances and transaction reconciliationBusiness Banking Context: Entity‑based account grouping for business users | Display account summaries and balancesShow transaction historyProvide check, deposit, or statement imagesBuild account and activity dashboards | Accounts (/api/generated/accounts/)Transactions (/api/generated/transactions/)Banking Activities (/api/generated/banking-activities/)Images (/api/generated/images/) | --- ## Business Banking {#business-banking} Business Banking APIs support onboarding and management of business customers and users. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | Registration– Create and track business registrations– Query by registration ID or confirmation numberBusiness Profile Management– Retrieve business details, users, and identifiersEntitlements & Limits– Retrieve business‑ and user‑level permissions– Enforce feature access and transaction limitsInstitution Configuration– Access FI‑specific business feature settings | Onboard new business customersTrack business registration statusEnforce business user permissions and limitsIntegrate business‑specific banking workflows | Registration (/api/generated/registration/)Profile (/api/generated/profile/)Entitlements (/api/generated/entitlements/) | --- ## Money Movement {#money-movement} Money Movement APIs manage recipients and execute transfers. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | Recipients– Create, validate, update, and delete payeesTransfers– One‑time and scheduled recurring transfers– Support internal, loan, and recipient transfers | Build money transfer functionalityManage payees and recipientsSchedule recurring or future‑dated paymentsSupport P2P or internal transfers | Recipients (/api/generated/recipients/)Transfers (/api/generated/transfers/) | --- ## Alerts And Notifications {#alerts-and-notifications} Alerts and Notifications APIs define types, deliver, and manage customer notifications across channels. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | Alert Types– Define alert configuration (Low Balance, Large Transaction)– Configure institution‑level alert availabilityTemplates– Create channel‑specific message templates– Support dynamic variable substitutionPreferences– Manage user and institution alert preferences– Configure thresholds and delivery channelsNotification Channels– Manage SMS, Email, Push, and Web destinationsHistory and Events– Publish alert events– Retrieve alert history and delivery status | Configure which alerts customers can receiveTrigger alerts for account or transaction eventsAllow users to manage alert preferencesTrack alert delivery and history | System Alerts (/api/generated/system-alerts/)Institution Alerts (/api/generated/institution-alerts/)Templates (/api/generated/templates/)Institution Preferences (/api/generated/institution-preferences/)User Preferences (/api/generated/user-preferences/)Notification Channels (/api/generated/notification-channels/)History And Events (/api/generated/history-and-events/) | --- ## Documents And Preferences {#documents-and-preferences} Documents and Preferences APIs manage disclosures, consent, and document delivery. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | Institution Disclosures– Create and manage regulatory disclosuresUser Disclosures– Track user acceptance and enrollment statusElectronic Statements– Manage electronic vs paper statement preferences– Support account‑ and user‑level enrollment | Present and track disclosure acceptanceEnable paperless statement enrollmentEnsure disclosure and regulatory complianceBuild digital consent workflows | Institution Disclosures (/api/generated/institution-disclosures/)User Disclosures (/api/generated/user-disclosures/)Electronic Statements (/api/generated/electronic-statements/) | --- ## Customer Campaigns {#customer-campaigns} Customer Campaigns APIs enable user segmentation for marketing and feature targeting. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | Experience Groups– Create and manage user cohorts– Bulk upload participants (ADD/ REMOVE/ REPLACE)Jobs– Monitor asynchronous batch operationsPromotions– Upload and manage audiences for Promotion SuiteAudience Management– Manage campaign user lists– Track upload processing and errors | Segment customers for marketing campaignsControl feature rollouts or experimentsPerform A/B testingDeliver targeted promotions | Experience Groups (/api/generated/experience-groups/)Jobs (/api/generated/jobs/)Promotions Suite (/api/generated/promotions-suite/)Audience (/api/generated/audience/) | --- ## MX {#mx} MX APIs integrate Candescent with MX Core Services through transparent gateway passthrough for **Platform**, **Real Time**, **Reporting**, and **SSO**. | Capabilities | When to Use | Reference Links | | --- | --- | --- | | **Platform**– Transparent passthrough to MX Platform APIs for aggregating and enhancing financial data across **users**, **members**, **institutions**, **accounts**, **transactions**, and **statements**– Unified access to external balances, transactions, and account context with data cleansing, categorization, and insights**Real Time**– Transparent passthrough for synchronous CRUD on **users**, **members**, **accounts**, **transactions**, and **holdings**– Push and synchronize institution core data with MX pipelines in real time**Reporting**– Transparent passthrough to retrieve daily MX change files by **date**, **resource**, and **action**– Self-describing **Avro** files with embedded schema metadata for batch ingestion**SSO**– Transparent passthrough for widget URLs and session authentication– Embed PFM and Financial Insights widgets via webview or iframe without exposing long-lived credentials | **Platform**– Aggregate external financial accounts and support end-to-end MX user lifecycle workflows– Access enhanced transaction data through the MX Platform pipeline**Real Time**– Push current balances, transactions, and holdings from core systems to MX-powered experiences– Keep user, member, and account data synchronized with MX in real time**Reporting**– Track platform-wide data changes without querying individual users– Enable operational reporting, reconciliation, and downstream analytics with daily change feeds**SSO**– Launch MX widgets (for example, Mini Budgets and other PFM experiences) in a webview or iframe– Authenticate users on the MX platform using SSO-based sessions and short-lived redirect URLs | Platform (/api/generated/mx-platform/)Real Time (/api/generated/real-time/)Reporting (/api/generated/reporting/)SSO (/api/generated/sso/) | --- ## Next Steps 1. **Quick Start Guide (/guides/getting-started/quickstart)** - Make your first API call 2. **Authentication Guide (/api/generated/o-auth-v-2/)** - Set up API access 3. **Error Codes Reference (/guides/getting-started/error-codes)** - Handle API errors 4. **API Reference (/api/generated/candescent-di-api/)** - Complete endpoint documentation --- ## API Error Codes Reference This comprehensive guide consolidates all error codes across the Candescent API platform. Refer to this guide to troubleshoot API responses and implement robust error handling in your application. ## Overview Candescent APIs return structured error responses in the following format: ``` { "code": "ERROR_CODE", "message": "Human-readable error description" } ``` Error codes follow a consistent naming convention: - **Prefix**: Indicates the API service (e.g., `ACC_`, `TXN_`, `CMN_`) - **Number**: Unique identifier within the service ## Quick Navigation | Category | Prefix | Description | | --- | --- | --- | | Authentication (#authentication-errors) | `90001`–`92000`, `CMN_` | OAuth token and common gateway errors | | Customer Management (#customer-management-errors) | `ISR_`, `UXU_`, Registration codes | Registration and access, profile and status, and contact information errors | | Core Banking (#core-banking-errors) | `ACC_`, `TXN_`, `BAS_`, `BIS_` | Accounts, transactions, banking activities, and images errors | | Business Banking (#business-banking-errors) | `BBS-`, `BBE-`, `BBP-` | Registration, profile, entitlements, and payments errors | | Money Movement (#money-movement-errors) | `REC_`, `TFR_` | Recipients and Transfers errors | | Alerts And Notifications (#alerts-and-notifications-errors) | `PRMSYS_`, `PRMVAL_`, `PRMAPS_` | System alerts, institution alerts, templates, institution and user preferences, notification channels, and history and events errors (Notification channels often use HTTP status only) | | Documents And Preferences (#documents-and-preferences-errors) | `DSC_`, `UXESTMT_` | Institution disclosures, user disclosures, and electronic statements errors | | Customer Campaigns (#customer-campaigns-errors) | `2000`–`2006`, `2009`, `3000`, HTTP status | Experience groups, jobs, promotions suite, and audience errors | | MX (#mx-errors) | — | Platform, Real Time, Reporting, and SSO passthrough errors; see Platform (/api/generated/mx-platform/), Real Time (/api/generated/real-time/), Reporting (/api/generated/reporting/), and SSO (/api/generated/sso/) | | --- | --- | | 90001 | app does not support client credentials | 403 | | 90001 | di_ficustomer not authorized | 401 | | 90001 | di_fiid not authorized | 401 | | 90001 | login credentials are not valid | 401 | | 90001 | Quota limit violation | 500 | | 90002 | Access blocked | 403 | | 90002 | Client not authorized for this URL | 403 | | 90002 | Form param 'grant_type' invalid | 400 | | 90002 | Form param 'password' invalid | 400 | | 90002 | Form param 'username' invalid | 400 | | 90002 | Header 'di_fiid' invalid | 400 | | 90002 | Header 'di_tid' invalid | 400 | | 90002 | Header 'originating_ip' invalid | 400 | | 90002 | Header invalid | 400 | | 90002 | Internal Service Error - contact DI team | 500 | | 90003 | Internal Service Error - contact DI team | 500 | | 90004 | Internal Service Error - contact DI team | 500 | | 91000 | Quota limit violation | 500 | | 92000 | Spike arrest violation | 500 | ## OAuth V2 (CMN_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | CMN_90000 | Internal server error | 500 | | CMN_90001 | Client not authorized to access this resource | 401 | | CMN_90001 | Internal server error | 500 | | CMN_90001 | Quota limit violation | 500 | | CMN_90002 | Spike limit violation | 500 | | CMN_90004 | Invalid credentials | 401 | | CMN_90005 | Header institutionId is invalid | 400 | | CMN_90005 | institutionUserId is invalid | 400 | | CMN_90006 | Not authorized to access this resource | 403 | | CMN_90007 | Invalid grant type | 400 | | CMN_90008 | Header transactionId is invalid | 400 | | CMN_90009 | Access blocked | 400 | | CMN_90010 | Header is invalid | 400 | | CMN_90011 | Request is invalid | 400 | | CMN_90012 | Request is invalid | 400 | | CMN_90013 | Username is invalid | 400 | | CMN_90014 | Password is invalid | 400 | | CMN_90015 | Invalid user credentials | 401 | | CMN_90016 | Invalid token | 400 | | CMN_90016 | Invalid user | 400 | | CMN_90017 | Request contains non printable ASCII characters | 400 | | CMN_90019 | Error creating token | 400 | ## Auth-Code (CMN_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | CMN_90000 | Internal server error | 500 | | CMN_90001 | Client not authorized to access this resource | 401 | | CMN_90001 | Internal server error | 500 | | CMN_90001 | Quota limit violation | 500 | | CMN_90002 | Spike limit violation | 500 | | CMN_90004 | Invalid client credentials | 400 | | CMN_90004 | Invalid credentials | 401 | | CMN_90005 | Header institutionId is invalid | 400 | | CMN_90005 | Form param institution_user_id is invalid | 400 | | CMN_90007 | Invalid grant type | 400 | | CMN_90008 | Header transactionId is invalid | 400 | | CMN_90009 | Access blocked | 400 | | CMN_90009 | Access blocked | 403 | | CMN_90010 | Header is invalid | 400 | | CMN_90012 | Request is invalid | 400 | | CMN_90013 | Username is invalid | 400 | | CMN_90017 | Request contains non printable ASCII characters | 400 | | CMN_90018 | Invalid token | 400 | | CMN_90019 | Error creating authorization code | 400 | | CMN_90020 | App cannot authorize itself | 400 | | CMN_90021 | Invalid client configuration | 400 | --- ## Customer Management Errors {#customer-management-errors} Customer Management APIs return errors related to registration and access, profile and status, and contact information errors. ## Registration and Access Errors **Registration Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | 20006 | Invalid input (member number, channel `TPV_API`, name length, SSN, etc.) | 400 | | 26201 | LoginID is already taken | 400 | | 26214 | Too many destinations passed | 400 | | 26330 | Registration already in progress (duplicate request) | 409 | | 26331 | User is already registered | 409 | | 26340 | Could not create record in database | 400 | | 220001 | SSN is not 9 digits | 400 | | 220002 | First name exceeds 39 characters | 400 | | 220003 | Last name exceeds 39 characters | 400 | | 220005 | Middle name exceeds 39 characters | 400 | | 220006 | Email exceeds 64 characters | 400 | | 220007 | Postal code not found | 400 | | 220008 | City not found | 400 | | 220009 | State not found or invalid length (US: 2 chars) | 400 | | 220010 | Street/Address1 missing or exceeds 128 characters | 400 | | 220011 | Country not found | 400 | | 220012 | Mother's maiden name missing or exceeds 128 characters | 400 | | 220013 | Invalid date of birth format | 400 | | 220014 | Phone number is missing | 400 | | 220015 | Invalid LoginID (6–256 chars, allowed `@$*_-=.!~`, no spaces) | 400 | | 220016 | LoginID cannot match member number | 400 | | 220018 | Invalid password | 400 | | 220019 | Login must be within preconfigured range | 400 | **Reset Password and Unlock User (UXU_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | UXU_10001 | Invalid JWT token | 400 | | UXU_10002 | Required role not present in JWT token | 403 | | UXU_10003 | JWT token has expired | 400 | | UXU_10004 | JWT token does not contain institution id | 400 | | UXU_10005 | Required Authorization header is missing | 400 | | UXU_10006 | Required Correlation Id header is missing | 400 | | UXU_10007 | Correlation Id is not a GUID | 400 | | UXU_10008 | Invalid IP address in the header | 400 | | UXU_10009 | Invalid Authorization in the header | 400 | | UXU_10010 | JWT token does not contain institution customers id | 400 | | UXU_10011 | JWT token institution customers id not matching path param | 400 | | UXU_10012 | Invalid path param | 400 | | UXU_10013 | Invalid path | 400 | | UXU_10014 | Invalid query param | 400 | | UXU_13001 | Combined firstname, middleName, lastname exceeds 39 chars | 400 | | UXU_13002 | Invalid user password | 400 | | UXU_13003 | Login Id is already taken | 400 | | UXU_13004 | You are already a registered user | 400 | | UXU_13005 | Invalid Date Format | 400 | | UXU_13006 | Soft failure, contact institution | 400 | | UXU_13007 | Login id and Member number can't be the same | 400 | | UXU_13008 | Member number/username is already registered | 409 | | UXU_13009 | Error while registering user | 400 | | UXU_30001 | Error interacting with the service | 503 | | UXU_30002 | Error interacting with the external service | 503 | | UXU_88888 | No entitled customers found | 404 | | UXU_88889 | Contact method Id not found | 400 | | UXU_88890 | Institution customer id not found | 400 | | UXU_88891 | Host phone postal address not found | 400 | | UXU_99998 | Internal server error | 500 | | UXU_99999 | Cannot handle this request — check URL, body and parameters | 400 | ## Profile and Status Errors **FI Customer Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | USER_ERROR | Bad Request - Invalid fiCustomerIdType | 400 | | APP_ERROR | Unauthorized Access | 401 | | APP_ERROR | FICustomer does not exist | 404 | | SYSTEM_ERROR | Internal server error | 500 | | SYSTEM_ERROR | Circuit breaker open or throttle limit reached | 503 | **Institution User and User Status (ISR_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | ISR_10000 | InstitutionId is invalid or its incorrectly configured | 400 | | ISR_10001 | InstitutionUser not found | 400, 404 | | ISR_10002 | Primary InstitutionUser not found | 400 | | ISR_10009 | Error processing OData expression | 400, 500 | | ISR_10010 | The CIF number is required, but was not found | 500 | | ISR_11001 | Full authentication was not provided in the request | 401 | | ISR_11002 | The authentication token that was sent in the request is invalid | 401 | | ISR_11003 | The authentication provided does not authorize this request | 403 | | ISR_11004 | Request should only contain printable ASCII characters | 400 | | ISR_11005 | Request is missing a transactionId header | 400 | | ISR_11006 | Request transactionId header is too long | 400 | | ISR_11007 | Invalid path param | 400 | | ISR_11008 | Invalid query param | 400 | | ISR_11009 | Request header callingAppId is too long | 400 | | ISR_23001 | Error interacting with FSG | 500 | | ISR_23002 | Error interacting with BBES | 500 | | ISR_23003 | Error interacting with BBK | 500 | | ISR_23004 | Error interacting with host | 500 | | ISR_23007 | Missing encryption key for this FI | 500 | | ISR_88888 | Internal validation error | 500 | | ISR_99999 | Internal server error | 500 | **Customer Profile (UXU_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | UXU_10001 | Invalid JWT token | 400 | | UXU_10002 | Required role not present in JWT token | 403 | | UXU_10003 | JWT token has expired | 400 | | UXU_10004 | JWT token does not contain institution id | 400 | | UXU_10005 | Required Authorization header is missing | 400 | | UXU_10006 | Required Correlation Id header is missing | 400 | | UXU_10007 | Correlation Id is not a GUID | 400 | | UXU_10008 | Invalid IP address in the header | 400 | | UXU_10009 | Invalid Authorization in the header | 400 | | UXU_10010 | JWT token does not contain institution customers id | 400 | | UXU_10011 | JWT token institution customers id not matching path param | 400 | | UXU_10012 | Invalid path param | 400 | | UXU_10013 | Invalid path | 400 | | UXU_10014 | Invalid query param | 400 | | UXU_30001 | Error interacting with the service | 503 | | UXU_30002 | Error interacting with the external service | 503 | | UXU_88888 | No entitled customers found | 404 | | UXU_88890 | Institution customer id not found | 400 | | UXU_99998 | Internal server error | 500 | | UXU_99999 | Cannot handle this request — check URL, body and parameters | 400 | ## Contact Information (UXU_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | UXU_10001 | Invalid JWT token | 400 | | UXU_10002 | Required role not present in JWT token | 403 | | UXU_10003 | JWT token has expired | 400 | | UXU_10004 | JWT token does not contain institution id | 400 | | UXU_10005 | Required Authorization header is missing | 400 | | UXU_10006 | Required Correlation Id header is missing | 400 | | UXU_10007 | Correlation Id is not a GUID | 400 | | UXU_10008 | Invalid IP address in the header | 400 | | UXU_10009 | Invalid Authorization in the header | 400 | | UXU_10010 | JWT token does not contain institution customers id | 400 | | UXU_10011 | JWT token institution customers id not matching path param | 400 | | UXU_10012 | Invalid path param | 400 | | UXU_10013 | Invalid path | 400 | | UXU_10014 | Invalid query param | 400 | | UXU_30001 | Error interacting with the service | 503 | | UXU_30002 | Error interacting with the external service | 503 | | UXU_88888 | No entitled customers found | 404 | | UXU_88889 | Contact method Id not found | 400 | | UXU_88890 | Institution customer id not found | 400 | | UXU_88891 | Host phone postal address not found | 400 | | UXU_99998 | Internal server error | 500 | | UXU_99999 | Cannot handle this request — check URL, body and parameters | 400 | --- ## Core Banking Errors {#core-banking-errors} Core Banking APIs return errors related to accounts, transactions, banking activities, and banking images. ## Accounts ## List Accounts and Get Account by ID (ACC_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | ACC_00002 | Given password is invalid | 401 | | ACC_00003 | The account is invalid for summary display | 500 | | ACC_00004 | The account is hidden | 500 | | ACC_00005 | Error processing filter expression | 400 | | ACC_00006 | 'From' Account restricted for transfer | 500 | | ACC_00007 | 'To' Account restricted for transfer | 500 | | ACC_00008 | Invalid 'From' account status for transfer | 500 | | ACC_00009 | Invalid 'To' account status for transfer | 500 | | ACC_00010 | 'From' Account has zero or negative balance | 500 | | ACC_00011 | Validation Error | 400 | | ACC_00012 | Data not found | 404 | | ACC_00014 | The CIF number is required, but was not found | 500 | | ACC_00015 | InstitutionId provided is invalid or blank | 400 | | ACC_00016 | InstitutionUserType provided is invalid or blank | 400 | | ACC_00017 | InstitutionCustomerId provided is invalid or blank | 400 | | ACC_00018 | InstitutionId from Query param and JWT do not match | 400 | | ACC_00019 | InstitutionUserType from Query param and JWT do not match | 400 | | ACC_00020 | InstitutionCustomerId from Query param and JWT do not match | 400 | | ACC_00021 | UserId provided is invalid or blank | 400 | | ACC_00022 | UserId from Query param and JWT do not match | 400 | | ACC_00023 | InstitutionUserId provided is invalid or blank | 400 | | ACC_00024 | InstitutionUserId from Query param and JWT do not match | 400 | | ACC_00025 | InstitutionUserRole provided is invalid or blank | 400 | | ACC_00026 | InstitutionUserRole from Query param and JWT do not match | 400 | | ACC_00101 | User not found | 404 | | ACC_00113 | Update nickname feature is not enabled | 403 | | ACC_00114 | Nickname field should not be empty | 400 | | ACC_00115 | Nick name update is disabled for Joint Accounts | 403 | | ACC_00116 | NickName length in request is greater than configured maximum length or Database column length | 400 | | ACC_00117 | Host update is done but exception occurred while updating the database | 500 | | ACC_00118 | Host update is done but exception occurred while inserting record to database | 500 | | ACC_00119 | Hide/show account feature is not enabled | 403 | | ACC_00201 | Account type ATYP not present in the account data | 500 | | ACC_00202 | Format error in generating formatted account id with mask configuration | 500 | | ACC_00203 | No USR value present in the Host Data | 500 | | ACC_00204 | ACHTYP is configuared as BLANK in FI config file | 500 | | ACC_00205 | ANUM information not provided by FI HOST | 500 | | ACC_00206 | No formatted account was produced by configuration | 500 | | ACC_00207 | Requested account type not found in FI configuration validAccountTypes | 500 | | ACC_00208 | MICR value not provided by FI host | 500 | | ACC_00209 | CIID Format configuration error | 500 | | ACC_00210 | EnableFormatter is not true for ACHTYPE CIID for FI | 500 | | ACC_00211 | Valid account types not set for Institution | 500 | | ACC_00300 | Utility DB is not available | 500 | | ACC_00408 | BB User is missing User Id in the request | 400 | | ACC_00410 | A location is required for BB users | 400 | | ACC_00500 | Requested service or feature is switched off | 500 | | ACC_00501 | Couchbase System is unavailable | 500 | | ACC_00600 | ServiceType parameter is invalid. Valid values are IB/BB | 400 | | ACC_00601 | Invalid JWT token | 401 | | ACC_00602 | Unauthorized access | 401 or 403 | | ACC_00702 | Subuser Id is empty | 400 | | ACC_00704 | InstitutionId is invalid or its incorrectly configured | 500 | | ACC_00705 | Member number is not valid. | 500 | | ACC_88888 | Internal validation error. | 500 | | ACC_99988 | Server can only handle JSON request. Other media types are not supported | 415 | | ACC_99989 | RequestBody size exceeds limit. | 400 | | ACC_99990 | Client error | 400 | | ACC_99991 | Request callingAppId header is too long | 400 | | ACC_99992 | One or more request query params are invalid or not provided. | 400 | | ACC_99993 | Server cannot handle this request | 500 | | ACC_99994 | Invalid query param | 400 | | ACC_99995 | Request should only contain printable ASCII characters | 400 | | ACC_99996 | Request header is too long | 500 | | ACC_99997 | Request transactionId header is too long | 400 | | ACC_99998 | Request is missing a transactionId header | 400 | | ACC_99999 | Error in Accounts Service | 500 | ## List Accounts (Legacy) Errors | Code | Type | Message | HTTP Status | | --- | --- | --- | --- | | 10001 | SYSTEM_ERROR | Internal System Error. | 500 | | 10002 | SYSTEM_ERROR | Connection Error. | 500 | | 10003 | SYSTEM_ERROR | Configuration Error. | 500 | | 10006 | SYSTEM_ERROR | Output validation error occurred | 500 | | 20009 | APP_ERROR | PrincipalEndUser:Data not found. | 404 | | 25002 | USER_ERROR | User Id or password is invalid | 500 | | 25099 | USER_ERROR | Required HTTP Headers were not found | 400 | | 25134 | SYSTEM_ERROR | Alt_mem_number required but not found in database | 500 | | 25401 | APP_ERROR | Account type ATYP not present in the account data. | 500 | | 25502 | APP_ERROR | Account formatter error | 500 | | 25503 | APP_ERROR | No USR value present in the Host Data | 500 | | 25504 | APP_ERROR | ACHTYP is configuared as BLANK in FI config file | 500 | | 25505 | APP_ERROR | ANUM information not provided by FI host | 500 | | 25506 | APP_ERROR | No formatted account was produced by configuration | 500 | | 25507 | APP_ERROR | Requested account type not found in FI configuration validAccountTypes | 500 | | 25518 | APP_ERROR | MICR value not provided by FI host | 500 | | 25519 | APP_ERROR | CIID Format configuration error | 500 | | 25520 | APP_ERROR | EnableFormatter is not true for ACHTYPE CIID in Fi config | 500 | | 25555 | APP_ERROR | Requested service or feature is switched off | 500 | | 25612 | APP_ERROR | Response from entitlements service is not successful | 500 | | 25615 | SYSTEM_ERROR | Entitlement Service is temporarily unavailable | 500 | | 25618 | USER_ERROR | Subuser auth ID is empty | 500 | | 25619 | APP_ERROR | Mismatch of the data between the requested resource and response returning | 500 | | 25665 | APP_ERROR | Extern format is not enabled/Invalid extern format | 500 | | 25673 | APP_ERROR | HTTP Response from BB Entitlements Service is not successful | 500 | | 25674 | SYSTEM_ERROR | BB Entitlement Service is temporarily unavailable | 500 | | 25679 | APP_ERROR | The user is not entitled for view account(s) | 500 | | 25690 | USER_ERROR | BB User is missing Auth ID Request Header | 500 | | 25693 | APP_ERROR | Invalid User Type Header for Business Banking User | 500 | | 25694 | APP_ERROR | Invalid User Type Header for IB User | 500 | | 25722 | SYSTEM_ERROR | HTTP Response from Business Customer Service is not successful | 500 | | 25723 | SYSTEM_ERROR | Business Customer Service is temporarily unavailable | 500 | | 25736 / 25737 | USER_ERROR | Invalid member number | 500 | | 28001 | SYSTEM_ERROR | Circuit Breaker HardTrip configuration set to true in FI config file | 503 | | 28002 | SYSTEM_ERROR | Circuit Breaker Status is Open | 503 | | 28003 | SYSTEM_ERROR | Incoming requests count exceeded configured Semaphore count | 503 | | 50000 | SYSTEM_ERROR | Internal error in downstream | 500 | | Host Code | - | Host Message | 500 | ## Retrieve Customer Accounts with Transactions (UXU_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | UXU_10002 | Required role not present in JWT token | 403 | | UXU_10003 | JWT token has expired | 400 | | UXU_10004 | JWT token is invalid, does not contain institution id | 400 | | UXU_10005 | Required Authorization header is missing | 400 | | UXU_10006 | Required Correlation Id header is missing | 400 | | UXU_10007 | Correlation Id is not a GUID | 400 | | UXU_10008 | Invalid IP address in the header | 400 | | UXU_10009 | Invalid Authorization in the header | 400 | | UXU_10010 | JWT token is invalid, does not contain institution customers id | 400 | | UXU_10011 | JWT token institution customers id is not matching customer id path param | 400 | | UXU_30001 | Error interacting with the service | 500 or 503 | | UXU_30002 | Error interacting with the external service | 500 or 503 | | UXU_88888 | No entitled customers found | 404 | ## Transactions (TXN_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | TXN_10001 | The date(s) provided could not be parsed, or represented an invalid range. | 400 | | TXN_10002 | Request is missing a transactionId header | 400 | | TXN_10003 | Request should only contain printable ASCII characters | 400 | | TXN_10004 | Request transactionId header is too long | 400 | | TXN_10005 | Invalid query param | 400 | | TXN_10006 | A valid institution customer id is required for business users. | 400 | | TXN_10007 | A valid account id is required. | 400 | | TXN_10008 | Request header is too long | 500 | | TXN_10009 | Request callingAppId header is too long | 400 | | TXN_10010 | One or more query params are invalid or blank | 400 | | TXN_10011 | The authorization for this request does not allow for one or more attributes to be passed as parameters | 400 | | TXN_11001 | Full authentication was not provided in the request. | 401 | | TXN_11002 | The authentication token that was sent in the request is invalid. | 401 | | TXN_11003 | The authentication provided does not authorize this request. | 403 | | TXN_11004 | Unauthorized access | 403 | | TXN_20001 | Transaction history is not enabled for this account. | 400 | | TXN_20002 | This user is not entitled to see transaction history for this account. | 400 | | TXN_20003 | Transactions for this account are available on an external site. | 400 | | TXN_20004 | The CIF number is required, but was not found | 400 | | TXN_20005 | Error processing filter expression | 400 | | TXN_20006 | Error processing pagination expression | 400 | | TXN_88888 | Internal validation error. | 500 | | TXN_90000 | Server cannot handle this request | 400, 404, or 500 | | TXN_99988 | Server can only handle JSON request. Other media types are not supported | 415 | | TXN_99990 | Client error | 400 | | TXN_99999 | Server error. | 500 | ## Banking Activities (BAS_) Errors | Code | Message | HTTP Status Code | | --- | --- | --- | | BAS_10001 | The given start date must be earlier than end Date. | 400 | | BAS_10002 | The given start date must be within last three months. | 400 | | BAS_10003 | BigTable connection failed. | 500 | | BAS_10004 | BigTable rows could not be read. | 500 | | BAS_10005 | Invalid arguments passed in the request; Failed to read HTTP message | 400 | | BAS_10006 | Http Message not readable | 400 | | BAS_10007 | NOT EQUAL and LIKE criterias not supported at this time. | 400 | | BAS_10008 | Additional filters condition and sub filter condition cannot be the same. | 400 | | BAS_10009 | Invalid UserType requested. | 400 | | BAS_10010 | Invalid UserIdType requested. | 400 | | BAS_10011 | UserIdType must be present if userId is given. | 400 | | BAS_10012 | Invalid EventType requested. | 400 | | BAS_10021 | BigTable Query is invalid. | 400 | | BAS_10022 | Row key is unexpectedly empty. | 400 | | BAS_10101 | Full authentication was not provided in the request. | 401 or 403 | | BAS_10102 | Authentication token sent in the request is invalid. | 401 | | BAS_10103 | The authentication provided does not authorize this request. | 400 | | BAS_10104 | The jwt token is invalid. | 401 | | BAS_10105 | Unauthorized access. | 400 | | BAS_10201 | Request should only contain printable ASCII characters | 400 | | BAS_10202 | transactionId header is too long | 400 | | BAS_10203 | One or more header values are invalid | 400 | | BAS_10204 | Invalid Request body | 400 | | BAS_10205 | One or more header values are too long | 400 | | BAS_10206 | nextPageToken is invalid | 400 | | BAS_10207 | Requested method type is invalid | 400 | | BAS_99999 | Internal server error | 500 | ## Images (BIS_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | BIS_00001 | Could not retrieve check image. Date out of range or expired. | 400 | | BIS_00002 | Could not retrieve requested image(s). Date out of range or expired. | 400 | | BIS_00003 | The date provided could not be parsed or represented an invalid date. | 400 | | BIS_00004 | Image type cannot be null or empty. | 400 | | BIS_00005 | Image type is not supported. | 400 | | BIS_00006 | Account type is not supported for check image. | 400 | | BIS_00007 | Account types configured for requested image(s) at FI level are invalid. | 400 | | BIS_00008 | Transaction types configured for requested image(s) at FI level are invalid. | 400 | | BIS_00009 | Transaction image number is invalid or contains non-numeric characters. | 400 | | BIS_00010 | Transaction date cannot be null for requested image(s). | 400 | | BIS_00011 | Account id cannot be null or empty. | 400 | | BIS_00012 | Card Number cannot be null or empty. | 400 | | BIS_00012 | Image identifier cannot be null for requested image(s). | 400 | | BIS_00013 | Request is missing a transactionId header | 400 | | BIS_00014 | Request should only contain printable ASCII characters. | 400 | | BIS_00015 | One of the query parameter length is greater than max length. | 400 | | BIS_00016 | Request transactionId header is too long. | 400 | | BIS_00017 | Invalid query param. | 400 | | BIS_00018 | Start date or end date cannot be null for statement images. | 400 | | BIS_00019 | The start date cannot be after the end date. | 400 | | BIS_00020 | A location is required for BB users. | 400 | | BIS_00021 | BB user is missing user id in the request. | 400 | | BIS_00022 | The date cannot be null or empty. | 400 | | BIS_00023 | Request header is too long. | 400 | | BIS_00024 | Request callingAppId header is too long. | 400 | | BIS_00025 | One or more query params are invalid or blank | 400 | | BIS_00026 | The authorization for this request does not allow for one or more attributes to be passed as parameters | 400 | | BIS_10000 | Client error. Banking images request could not be completed. | 400 | | BIS_10001 | Full authentication was not provided in the request. | 401 | | BIS_10002 | The authentication token that was sent in the request is invalid. | 401 | | BIS_10003 | The authentication provided does not authorize this request. | 403 | | BIS_10004 | InstitutionCustomers not available in JWT. | 403 | | BIS_10005 | Unauthorized access. | 401 or 403 | | BIS_20001 | Check image retrieval was not successful. | 500 | | BIS_20002 | No statements available for users | 200 (warning) | | BIS_20007 | Error interacting with FICDS Statement Image service. | 200 (warning) | | BIS_20008 | No transaction found for the requested image. | 404 | | BIS_20009 | Account in the request not available | 404 | | BIS_20022 | User not found. | 404 | | BIS_20023 | HTTP Response from BB Service is not successful | 500 | | BIS_30000 | Check image feature is not enabled for this FI. | 400 | | BIS_30001 | Image retrieval is turned off for this account. | 400 | | BIS_30002 | Image(s) retrieval is turned off for this FI. | 400 | | BIS_30004 | Data not found. | 404 | | BIS_30005 | User is not entitled to view online statements. | 400 or 401 | | BIS_30006 | Entitlements or account response is blank. | 400 | | BIS_88888 | Internal validation error. | 500 | | BIS_90000 | Server cannot handle this request. | 500 | | BIS_99988 | Server can only handle JSON request. Other media types are not supported | 415 | | BIS_99999 | Server error. Banking images request could not be completed. | 500 | --- ## Business Banking Errors {#business-banking-errors} Business Banking APIs returns errors related to registration, profile, and entitlements. ## Registration (BBS_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | BBS-40095 | Invalid tinNumber | 400 | | BBS-40095 | Invalid confirmationNumber | 400 | | BBS-40095 | Invalid institutionId | 400 | | BBS-40150 | Invalid JWT | 401 | | BBS-40151 | Invalid roles or entitlements | 403 | | BBS-40153 | Unexpected server error | 500 | | BBS-40154 | Business registration not found | 404 | ## Profile (BBS_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | BBS-40095 | Invalid tinNumber | 400 | | BBS-40095 | Invalid searchType | 400 | | BBS-40095 | Invalid institutionId | 400 | | BBS-40147 | Business details not found | 400 | | BBS-40150 | Invalid JWT | 401 | | BBS-40151 | Invalid roles or entitlements | 403 | | BBS-40153 | Unexpected server error | 500 | ## Entitlements (BBE_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | BBE-41107 | Error in retrieving institution user | 500 | | BBE-41108 | Invalid JWT | 401 | | BBE-41109 | Invalid roles or entitlements | 403 | | BBE-41110 | Required request parameter 'businessId' not present | 400 | | BBE-41111 | Unexpected server error | 500 | ## Payments (BBP_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | BBP-126 | Invalid institution Id | 400 | | BBP-127 | Invalid business Id | 400 | | BBP-128 | Invalid login Id | 400 | | BBP-129 | Invalid SEC code | 400 | | BBP-130 | Invalid transaction | 400 | | BBP-131 | Invalid JWT | 401 | | BBP-132 | Invalid role | 401 | | BBP-133 | Bad request | 400 | | BBP-133 | Query parameters (fromDate, toDate) are required | 400 | | BBP-133 | Missing or invalid payment id | 400 | | BBP-134 | No record exists for the id | 404 | | BBP-135 | Invalid User. User not found in System | 400 | | BBP-136 | Invalid payment type | 400 | | BBP-137 | Invalid payment status | 400 | | BBP-138 | Invalid payment | 400 | | BBP-139 | Invalid ACH payment description | 400 | | BBP-140 | Invalid payment amount | 400 | | BBP-141 | Invalid ACH CompanyId | 400 | | BBP-142 | Invalid currency code | 400 | | BBP-143 | Invalid transaction type | 400 | | BBP-144 | Invalid account type | 400 | | BBP-145 | Invalid routing number | 400 | | BBP-146 | Invalid contact name | 400 | | BBP-147 | Invalid contact account number | 400 | | BBP-148 | Invalid originator account number | 400 | | BBP-149 | Invalid addenda | 400 | | BBP-150 | Invalid contact identification number | 400 | | BBP-151 | Invalid delivery date | 400 | | BBP-152 | Invalid header value for request. | 400 | | BBP-153 | Invalid contact bank name | 400 | | BBP-154 | Invalid beneficiary details | 400 | | BBP-155 | Invalid beneficiary name | 400 | | BBP-156 | Invalid beneficiary address | 400 | | BBP-157 | Invalid beneficiary address street | 400 | | BBP-158 | Invalid beneficiary address city | 400 | | BBP-159 | Invalid beneficiary address state | 400 | | BBP-160 | Invalid beneficiary address zip code | 400 | | BBP-161 | Invalid beneficiary address country | 400 | | BBP-162 | Invalid purpose of wire | 400 | | BBP-163 | Invalid beneficiary account number | 400 | | BBP-164 | Invalid beneficiary instructions | 400 | | BBP-165 | Invalid beneficiary bank details | 400 | | BBP-166 | Invalid beneficiary bank name | 400 | | BBP-167 | Invalid beneficiary routing number | 400 | | BBP-168 | Invalid beneficiary SWIFT number | 400 | | BBP-169 | Invalid beneficiary account number | 400 | | BBP-170 | Invalid beneficiary bank instructions | 400 | | BBP-171 | Invalid beneficiary bank address 1 | 400 | | BBP-172 | Invalid beneficiary bank address 2 | 400 | | BBP-173 | Invalid beneficiary bank address city | 400 | | BBP-174 | Invalid beneficiary bank address state | 400 | | BBP-175 | Invalid beneficiary bank address zip code | 400 | | BBP-176 | Invalid beneficiary bank address country | 400 | | BBP-177 | Invalid intermediary bank details | 400 | | BBP-178 | Invalid intermediary bank type | 400 | | BBP-179 | Invalid intermediary bank account number | 400 | | BBP-180 | Invalid intermediary bank name | 400 | | BBP-181 | Invalid intermediary routing number | 400 | | BBP-182 | Invalid intermediary bank SWIFT number | 400 | | BBP-183 | Invalid foreign currency amount | 400 | | BBP-184 | Invalid send in foreign currency | 400 | | BBP-185 | Invalid payment name | 400 | --- ## Money Movement Errors {#money-movement-errors} Money Movement APIs return errors related to recipients and transfers. ## Recipients (REC_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | REC_10005 | User not found at host | 400 | | REC_10006 | Invalid passcode | 400 | | REC_10007 | Invalid account | 400 | | REC_10008 | Test lucky transfer failed | 500 | | REC_10009 | Invalid query param | 400 | | REC_11001 | Full authentication was not provided in the request | 401 | | REC_11002 | The authentication token is invalid | 401 | | REC_11003 | The authentication does not authorize this request | 403 | | REC_11004 | InstitutionId is invalid or incorrectly configured | 400 | | REC_12001 | Request should only contain printable ASCII characters | 400 | | REC_12002 | Request is missing a transactionId header | 400 | | REC_12003 | Request transactionId header is too long | 400 | | REC_12004 | Required fields are not provided or not valid | 400 | | REC_12005 | Request cannot be blank | 400 | | REC_12006 | Recipient id cannot be blank | 400 | | REC_12007 | Provider type cannot be blank | 400 | | REC_12008 | Invalid provider type | 400 | | REC_12009 | Invalid email | 400 | | REC_12010 | Recipient ids from request and URL do not match | 400 | | REC_12011 | Request field length exceeds max length | 400 | | REC_12012 | Account type is not from the list of allowed types | 400 | | REC_12013 | Sender account id cannot be blank | 400 | | REC_12014 | Request header is too long | 400 | | REC_12015 | Some fields in the request body are not supported for the configured provider type | 400 | | REC_13001 | This recipient already exists | 400 | | REC_13002 | This recipient nickname already exists | 400 | | REC_14001 | Recipient not added to the database successfully | 500 | | REC_14002 | Recipient not deleted successfully | 500 | | REC_14003 | Error while fetching recipients from database | 500 | | REC_14004 | Recipient not found | 400 | | REC_14005 | Error while updating recipient information | 400, 401, or 500 | | REC_22001 | Internal validation error | 500 | | REC_99997 | Client error | 400 | | REC_99998 | Server cannot handle this request | 400, 404, or 405 | | REC_99999 | Server error | 500 | ## Transfers (TFR_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | TFR_10000 | Client error. Transfer could not be completed | 400 | | TFR_10001 | Server error. Transfer could not be completed | 500 | | TFR_10002 | Invalid institution id | 400 | | TFR_10003 | The From account does not exist or could not be retrieved | 400 | | TFR_10004 | The To account does not exist or could not be retrieved | 400 | | TFR_10005 | An unacceptable transfer type was provided for this transfer | 400 | | TFR_10006 | Contributions to a prior year cannot be scheduled | 400 | | TFR_10007 | A start date must be provided, and must be after today | 400 | | TFR_10008 | An end date after the start date must be provided and must yield at least one execution | 400 | | TFR_10009 | The number of executions is required for the given life type (positive integer ≤ 99) | 400 | | TFR_10010 | The provided frequency requires a valid day or set of days to execute on | 400 | | TFR_10011 | The provided schedule requires a life type | 400 | | TFR_10012 | The provided schedule requires a valid frequency | 400 | | TFR_10013 | Loan overpayment cannot be scheduled | 400 | | TFR_10014 | SRTs are not enabled for this institution | 400 | | TFR_10015 | Loan overpayment is not enabled for this institution | 400 | | TFR_10016 | Loan overpayment options are not configured for this institution | 400 | | TFR_10017 | Loan overpayment options for this institution could not be processed | 400 | | TFR_10018 | Loan overpayment is not allowed for the To account | 400 | | TFR_10019 | Loan overpayment option is not allowed for the To account | 400 | | TFR_10020 | The transfer amount is required | 400 | | TFR_10021 | The transfer amount is invalid | 400 | | TFR_10022 | The transfer amount exceeds the From account balance | 400 | | TFR_10023 | The From User is required | 400 | | TFR_10024 | The To User is required | 400 | | TFR_10025 | The From account is restricted from making a transfer | 400 | | TFR_10026 | The To account is restricted from receiving a transfer | 400 | | TFR_10027 | The From account has an invalid status and cannot be used to make a transfer | 400 | | TFR_10028 | The To account has an invalid status and cannot be used to receive a transfer | 400 | | TFR_10029 | The From account and To account cannot be the same | 400 | | TFR_10030 | The RegE confirmation message could not be created | 400 | | TFR_10031 | The transfer amount must equal the To account loan payment amount | 400 | | TFR_10032 | The transfer amount must be less than or equal to the To account loan payment amount | 400 | | TFR_10033 | The transfer amount must be greater than or equal to the To account loan payment amount | 400 | | TFR_10034 | Invalid query param | 400 | | TFR_10035 | Request should only contain printable ASCII characters | 400 | | TFR_10036 | Request is missing a transactionId header | 400 | | TFR_10037 | Request transactionId header is too long | 400 | | TFR_10038 | The To account prior year eligible contribution amount is missing, zero, or negative | 400 | | TFR_10039 | The transfer amount exceeds the prior year eligible contribution amount | 400 | | TFR_10040 | The To account eligible contribution amount is missing, zero, or negative | 400 | | TFR_10041 | The transfer amount exceeds the eligible contribution amount | 400 | | TFR_10042 | Memo is not enabled for this institution | 400 | | TFR_10043 | Memo exceeds maximum length allowed | 400 | | TFR_10044 | Memo contains an invalid character | 400 | | TFR_10045 | Transfers From the institution owned account transfer type is not enabled | 400 | | TFR_10046 | Transfers To the institution owned account transfer type is not enabled | 400 | | TFR_10047 | The institution owned account is not properly configured for this institution | 400 | | TFR_10048 | The cross TIN transfer type was set incorrectly | 400 | | TFR_10050 | Recipient transfers not allowed | 400 | | TFR_10051 | Recipient not found | 400 | | TFR_10052 | Recipient transfers to the requested account type not allowed | 400 | | TFR_10053 | Invalid to account type in validate recipient transfer request | 400 | | TFR_10054 | Invalid to passcode in validate recipient transfer request | 400 | | TFR_10056 | The request body could not be parsed; ensure required fields and valid values | 400 | | TFR_10057 | Business banking user not found | 400 | | TFR_10058 | The fromAccountId field is required | 400 | | TFR_10059 | The toAccountId field is required | 400 | | TFR_10060 | The CIF number is required, but was not found | 401 | | TFR_10061 | Request callingAppId header is too long | 400 | | TFR_10062 | The provided schedule is invalid for the life type and frequency | 400 | | TFR_10063 | An incorrect number of days was provided for the given frequency | 400 | | TFR_10064 | Test transfers cannot be scheduled | 400 | | TFR_10065 | Request header is too long | 400 | | TFR_10066 | Transfer id is required | 400 | | TFR_10067 | Transfer ids from request and URL do not match | 400 | | TFR_10068 | Unauthorized access | 403 | | TFR_11001 | Full authentication was not provided in the request | 401 | | TFR_11002 | The authentication token is invalid | 401 | | TFR_11003 | The authentication does not authorize this request | 403 | --- ## Alerts And Notifications Errors {#alerts-and-notifications-errors} Alerts and Notifications APIs return errors related to system alerts, institution alerts, templates, institution and user preferences, notification channels, and history and events ## System Alert, Institution Alert, Templates Errors **System (PRMSYS_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | PRMSYS_10001 | Cross talk / concurrency error occurred | 400 | | PRMSYS_10002 | Malformed input data | 400 | | PRMSYS_10003 | Unknown application error occurred | 400 | | PRMSYS_10004 | Error occurred while validating JWT token | 400 | | PRMSYS_10005 | Resource of name already exists | 204 | | PRMSYS_10006 | Requested resource of identifier doesn't exist | 400 | | PRMSYS_10007 | Resource of identifier already exists | 400 | | PRMSYS_10008 | Requested resource of name doesn't exist | 400 | | PRMSYS_10015 | Required attribute missing | 400 | | PRMSYS_10016 | Non Printable ASCII character detected | 400 | **Validation (PRMVAL_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | PRMVAL_10001 | Path parameter doesn't match request body value | 400 | | PRMVAL_10002 | Invalid value for field | 400 | | PRMVAL_10003 | Invalid institution | 400 | | PRMVAL_10005 | Invalid channel type | 400 | | PRMVAL_10006 | Invalid alert type | 400 | | PRMVAL_10007 | Field is required | 400 | | PRMVAL_10008 | Field is invalid | 400 | ## Institution and User Preferences Errors **Alert preferences (PRMAPS_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | PRMAPS_10007 | Invalid alert preference ID | 404 | | PRMAPS_10008 | Alert preference mismatch | 400 | **Validation (PRMVAL_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | PRMVAL_10004 | Invalid user | 400 | | PRMVAL_10006 | Invalid alert type | 400 | | PRMVAL_10009 | Requested alert type was not found for the FI | 400 | | PRMVAL_10010 | Preference not found for enrollmentId | 400 | | PRMVAL_10011 | Preference not found for institution | 400 | | PRMVAL_10012 | Value should not be null | 400 | | PRMVAL_10013 | Invalid alert preference | 400 | | PRMVAL_10015 | Alert type not configured for channel or disabled for Institution | 400 | | PRMVAL_10016 | Unsupported account type | 400 | ## Notification Channels Errors | HTTP Status | Message | | --- | --- | | 400 | Missing Required HTTP Headers or Invalid/Missing Inputs | | 401 | Authorization invalid or Missing Authorization Header | | 404 | Entities not Found (User or Account not found) | | 500 | Internal Server Error | ## History and Events Errors **Alert History (PRMSYS_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | PRMSYS_10003 | Unknown application error occurred | 400 | | PRMSYS_10004 | Error occurred while validating JWT token | 400 | | PRMSYS_10009 | Resource doesn't exist for the provided search criteria | 500 | | PRMSYS_10011 | Unauthorized access to the resource | 404 | | PRMSYS_10012 | Unauthorized access — JWT value mismatch | 404 | | PRMVAL_10014 | Invalid date format | 400 | **Realtime Publish (PRMSYS_) Errors:** | Code | Message | HTTP Status | | --- | --- | --- | | PRMSYS_10002 | Malformed input data | 500 | | PRMSYS_10003 | Missing eventDetails or notification | 500 | | PRMSYS_10007 | Missing mandatory fields | 500 | | PRMSYS_10008 | Invalid institutionId | 500 | | PRMSYS_10013 | Missing Authorization Token | 500 | --- ## Documents And Preferences Errors {#documents-and-preferences-errors} Documents and Preferences APIs return errors related to institution disclosures (/api/generated/institution-disclosures/), user disclosures (/api/generated/user-disclosures/), and electronic statements (/api/generated/electronic-statements/). ## Institution and User Disclosures (DSC_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | DSC_10002 | Invalid request. | 400 | | DSC_10003 | Invalid operation. | 501 | | DSC_10009 | Invalid query param. | 400 | | DSC_11001 | Full authentication was not provided in the request. | 401 | | DSC_11002 | The authentication token that was sent in the request is invalid. | 401 | | DSC_11003 | The authentication provided does not authorize this request. | 401 | | DSC_11004 | A location id is required for business banking users | 400 | | DSC_12001 | Request should only contain printable ASCII characters. | 400 | | DSC_12002 | Request is missing a transactionId header. | 400 | | DSC_12003 | Request transactionId header is too long. | 400 | | DSC_12004 | Required fields are not provided or not valid. | 400 | | DSC_12005 | Request cannot be blank. | 400 | | DSC_12006 | Invalid or empty account type in request. | 400 | | DSC_12007 | Request header is too long | 400 | | DSC_12011 | One of the request field length is greater than max length. | 400 | | DSC_12012 | Disclosure ids from request body and URL do not match. | 400 | | DSC_12013 | Request callingAppId header is too long. | 400 | | DSC_12014 | RequestBody size exceeds limit. | 400 | | DSC_12015 | Disclosure not supported | 400 | | DSC_12016 | Account Id is missing in disclosure | 400 | | DSC_12017 | Paper waiver field is missing in disclosure | 400 | | DSC_13001 | Data not found for user | 400 | | DSC_13002 | Disclosures are not retrieved successfully. | 500 | | DSC_13003 | Disclosures are not created successfully. | 500 | | DSC_13004 | Disclosures are not updated successfully. | 500 | | DSC_13005 | The CIF number is required, but was not found | 400 | | DSC_22001 | Internal validation error. | 500 | | DSC_23002 | Error interacting with CBS Service | 500 | | DSC_23003 | Error interacting with CAS Service | 500 | | DSC_23004 | Error interacting with NIIS Service | 500 | | DSC_23005 | Error interacting with Accounts Service | 500 | | DSC_90000 | Server cannot handle this request. | 400 | | DSC_99997 | Client error | 400 | | DSC_99999 | Internal server error. | 500 | ## Electronic Statements (UXESTMT_) Errors | Code | Message | HTTP Status | | --- | --- | --- | | UXESTMT_10001 | Required Authorization header is missing | 400 | | UXESTMT_10002 | Invalid JWT token | 400 | | UXESTMT_10003 | Required role not present in JWT token | 403 | | UXESTMT_10004 | JWT token has expired | 400 | | UXESTMT_10005 | JWT token is invalid, does not contain institution id | 400 | | UXESTMT_10006 | JWT token is invalid, does not contain institution customers id | 400 | | UXESTMT_10007 | Required Correlation Id header is missing | 400 | | UXESTMT_10008 | Correlation Id is not a GUID | 400 | | UXESTMT_10011 | Invalid IP address in the header | 400 | | UXESTMT_10012 | Invalid Authorization in the header | 400 | | UXESTMT_11007 | Invalid path param | 400 | | UXESTMT_11008 | Invalid path | 404 | | UXESTMT_11010 | Required input fields are missing | 400 | | UXESTMT_11012 | The given 'accountId' is not available in user disclosure. | 400 | | UXESTMT_11013 | User disclosure should be in 'ACCEPTED' status. | 400 | | UXESTMT_11014 | 'institutionId' is invalid or it's incorrectly configured. | 400 | | UXESTMT_11015 | The days difference should not be greater than 90 days | 400 | | UXESTMT_11016 | 'fromDate' can not be greater than 'toDate'. | 400 | | UXESTMT_11017 | Invalid date format, the date format should be `dd-MM-yyyy` or `yyyy-MM-dd'T'HH:mm:ssXXX` | 400 | | UXESTMT_11018 | Invalid request, please check the input parameters. | 400 | | UXESTMT_11019 | 'fromDate' and 'toDate' can not be same. | 400 | | UXESTMT_11020 | No accounts are available in user disclosure to update. | 400 | | UXESTMT_11021 | Multi-statement functionality is not set up for this institution. | 400 | | UXESTMT_30001 | Error interacting with the service | 500 or 503 | | UXESTMT_30002 | Error interacting with the external service | 500 or 503 | | UXESTMT_30003 | Disclosure not available. | 503 | | UXESTMT_88888 | No entitled customers found. | 404 | | UXESTMT_88889 | The given user is not active. | 400 | | UXESTMT_88891 | Disclosures name is not available for the given 'accountId.' | 404 | | UXESTMT_99998 | Cannot handle this request. Please check the url, request body and parameters. | 400, 500, or 503 | --- ## Customer Campaigns Errors {#customer-campaigns-errors} Customer Campaigns APIs return errors related to experience groups (/api/generated/experience-groups/), jobs (/api/generated/jobs/), promotions suite (/api/generated/promotions-suite/), and audience (/api/generated/audience/). ## Experience Groups Errors | Code | Message | HTTP Status | | --- | --- | --- | | 2000 | Invalid groupId \{groupId\} | 400 | | 2000 | groupId \{groupId\} not found or has been marked for deletion | 400 | | 2000 | Content-Type must be multipart/form-data or multipart/mixed | 400 | | 2000 | Invalid type value. Type value can only be ADD, REMOVE, or REPLACE. | 400 | | 2000 | Type parameter is required. | 400 | | 2000 | Uploaded file data is empty. | 400 | | 2000 | File type: \{contentType\} not allowed. | 400 | | 2000 | \{field\} is required | 400 | | 2000 | \{field\} cannot exceed \{max\} characters | 400 | | 2001 | There are import jobs in process, need to wait for them to finish. | 400 | | 2001 | Additional details may be available in server logs | 500 | | 2003 | Invalid Authorization | 401 | | 2004 | A group with name \{groupName\} already exists. | 400 | ## Jobs Errors | Code | Message | HTTP Status | | --- | --- | --- | | 2000 | 'jobId' \{jobId\} not found | 400 | | 2001 | additional details may be available in server logs | 500 | | 2003 | Invalid Authorization | 401 | ## Promotions Suite Errors | HTTP Status | Message | | --- | --- | | 400 | User list can't be empty | | 400 | User list name can't be empty | | 400 | User list name must not be empty | | 400 | User list name should not be more than 50 characters | | 400 | User list name should not contain special characters | | 400 | User list description should not be more than 200 characters | | 400 | User list description should not contain special characters | | 400 | Malformed request: the uuid \{jobId\} doesn't have the right format. Please check the uuid and retry. | | 400 | No job status found for the given job ID | | 401 | There was an authorization error. Check that the correct credentials have been supplied. | | 404 | No job found for the given `jobId` and `fiId` (empty response body) | | 429 | Too many user lists are awaiting processing. Please try again later. | | 500 | An unexpected error occurred while handling the request. | ## Audience Errors | Code | Message | HTTP Status | | --- | --- | --- | | 401 | Invalid JWT | 401 | | 2001 | Exception occurred while processing the request in the application | 500 | | 2003 | Invalid header value : \{header\} | 400 | | 2005 | Missing header : \{header\} | 400 | | 2006 | \{header\} Cannot be empty or null | 400 | | 2009 | File Metadata input is incomplete, please provide all mandatory fields [userlistFileName,userlistName,userlistOperation] | 400 | | 2009 | FileName is not in the required format FI<fiId>_filename_<yyyyMMddHHmmss>.csv | 400 | | 2009 | Invalid operation name provided. Please provide one of these valid values [ADD, CREATE, CREATE_OR_REPLACE, CREATE_OR_ADD, REMOVE, REPLACE] | 400 | | 2009 | Metadata already exists for the filename \{userlistFileName\} | 400 | | 2009 | Input request is incomplete, please provide all mandatory fields [userlistFileName,viewName] | 400 | | 2009 | Input request is incomplete, please provide mandatory field [userlistFileName] | 400 | | 2009 | Input request is incomplete, please provide mandatory field [viewName] | 400 | | 2009 | Invalid viewname provided.Please provide one of these valid values [fileErrorReport, fileStatus] | 400 | | 2009 | No details exist in the system for the given filename. | 400 | | 2009 | Malformed JSON request | 400 | | 3000 | Validation Failed | 400 | --- ## MX Errors {#mx-errors} MX APIs integrate Candescent with MX Core Services through transparent gateway passthrough for **Platform**, **Real Time**, **Reporting**, and **SSO**. Responses may contain Candescent gateway errors before a request reaches MX, or MX upstream errors returned unchanged from the target MX service. For the full OAuth V2 gateway error catalog, see Authentication Errors (#authentication-errors). ## Candescent API Gateway Errors All MX passthrough APIs apply the same Candescent gateway controls before forwarding requests to MX: | Code | Message | HTTP Status | | --- | --- | --- | | CMN_90000 | Internal server error | 500 | | CMN_90001 | Client not authorized to access this resource | 401 | | CMN_90001 | Quota limit violation | 500 | | CMN_90002 | Spike limit violation | 500 | | CMN_90008 | Header correlationId is invalid | 400 | | CMN_90010 | Header correlationId is required | 400 | | CMN_90010 | Header ext_host is required | 400 | | CMN_90011 | Invalid or unsupported ext_host | 400 | | CMN_90018 | Invalid token | 400 | For **Real Time**, **Reporting**, and **SSO** passthrough APIs, `CMN_90001` (`Client not authorized to access this resource`) may also indicate that the request path does not include the institution identifier from the OAuth V2 token. ## Platform Errors MX Platform upstream errors are returned unchanged from MX. Error codes and semantics are defined by MX: - MX Platform APIs v20250224 errors (https://docs.mx.com/api-reference/platform-api/overview/errors) - MX Platform APIs v20111101 errors (https://docs.mx.com/api-reference/platform-api/v20111101/overview/errors) ## Real Time Errors MX Real Time upstream errors are returned unchanged from MX. Error codes and semantics are defined by MX: - MX Real Time APIs errors (https://docs.mx.com/api-reference/more-apis/mdx/mdx-real-time/#errors) ## Reporting Errors MX Reporting upstream errors are returned unchanged from MX. Error codes and semantics are defined by MX: - MX Reporting APIs errors (https://docs.mx.com/api-reference/more-apis/reporting/requirements#errors) ## SSO Errors MX SSO upstream errors are returned unchanged from MX. Error codes and semantics are defined by MX: - MX SSO APIs errors (https://docs.mx.com/api-reference/sso/v3/api-requirements#http-status-codes) --- ## Error Handling Best Practices 1. Check HTTP Status ``` if (response.status === 401) { // Token expired or invalid - refresh token or re-authenticate } else if (response.status === 403) { // Insufficient permissions - check required scopes } else if (response.status === 400) { // Client error - check request parameters } else if (response.status >= 500) { // Server error - implement retry with exponential backoff } ``` 2. Parse Error Codes ``` const errorResponse = await response.json(); const errorCode = errorResponse.code; switch (errorCode) { case 'CMN_90004': // Invalid credentials - prompt for new credentials break; case 'CMN_90016': // Invalid token - refresh access token break; case 'TFR_10022': // Insufficient funds - notify user break; default: // Log error and display generic message } ``` 3. Implement Retry Logic For transient errors (5xx, rate limits), implement exponential backoff: ``` async function makeRequestWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await fetch(url, options); if (response.ok) return response; const error = await response.json(); // Retry on rate limits or server errors if (['CMN_90002'].includes(error.code) || response.status >= 500) { const delay = Math.pow(2, attempt) * 1000; // Exponential backoff await new Promise(resolve => setTimeout(resolve, delay)); continue; } throw new Error(error.message); } } ``` 4. Log Errors with Context Always include the `transactionId` header value in your logs when troubleshooting with Candescent support: ``` console.error({ transactionId: requestHeaders['transactionId'], errorCode: error.code, errorMessage: error.message, endpoint: url, timestamp: new Date().toISOString() }); ``` --- ## Related Resources - API Categories Overview (/guides/getting-started/api-overview) - API overview and quick references - Authentication Guide (/api/generated/o-auth-v-2/) - Token management and OAuth flows - API Reference (/api/generated/candescent-di-api/) - Complete API documentation - Getting Started (/guides/getting-started/quickstart) - Initial setup and making your first API call --- ## OAuth V1 Token — Request Body Rendering Review **Document purpose:** Review of why `grant_type` (a required request body field) does not render correctly in the OAuth V1 token endpoint documentation and API playground. **Endpoint:** `POST /v1/oauth/token` **Docs page:** Create OAuth Token (V1) — `/api/generated/create-access-token-v-1/` **Date:** July 7, 2026 **Status:** For review ## Background The OAuth V1 token endpoint accepts a form-urlencoded body with a required `grant_type` field. Two grant types are supported: | Grant type | Purpose | Additional required fields | |------------|---------|----------------------------| | `client_credentials` | Institution-scoped token | None | | `password` | Customer-scoped token (retail only) | `username`, `password` | The endpoint also requires four headers: `Authorization` (Basic), `di_tid`, `di_fiid`, and `Content-Type`. --- ## What the OpenAPI spec defines ## Request body schema: `AccessTokenRequestV1` The body schema is defined as a **`oneOf`** with two variants, each using **`allOf`** to compose a shared base schema: ``` AccessTokenRequestV1 (oneOf) ├── ClientCredentialsGrantRequestV1 │ └── allOf │ ├── TokenRequestBaseV1 ← required: [grant_type] │ └── grant_type enum + metadata │ └── PasswordGrantRequestV1 └── allOf ├── TokenRequestBaseV1 ← required: [grant_type] └── required: [username, password] + grant_type enum ``` ## Base schema: `TokenRequestBaseV1` ``` TokenRequestBaseV1: type: object required: - grant_type properties: grant_type: type: string description: OAuth grant type for the token request. ``` **Conclusion:** The spec correctly marks `grant_type` as required. The requirement is attached to `TokenRequestBaseV1`, which is composed into each grant variant via `allOf`. ## Decoded schema shape (as stored in generated docs) The generated API page stores the resolved schema approximately as: ``` { "description": "OAuth token request payload...", "oneOf": [ { "title": "ClientCredentialsGrantRequestV1", "allOf": [ { "type": "object", "required": ["grant_type"], "properties": { "grant_type": { "type": "string" } }, "title": "TokenRequestBaseV1" }, { "type": "object", "properties": { "grant_type": { "type": "string", "enum": ["client_credentials", "password"], "example": "client_credentials" } } } ] }, { "title": "PasswordGrantRequestV1", "allOf": [ "... TokenRequestBaseV1 ...", "... username, password ..." ] } ], "title": "AccessTokenRequestV1" } ``` Note: There is **no top-level `"type": "object"`** on `AccessTokenRequestV1`. --- ## Observed behavior ## 1. API playground request block (interactive form) **Expected:** Form fields for `grant_type` (and conditionally `username` / `password`). **Actual:** No form fields. The body area shows an empty text editor (LiveEditor) instead. **Root cause:** The theme's `Body` component only renders form fields for `application/x-www-form-urlencoded` when the schema has `schema.type === "object"`: ``` // docusaurus-theme-openapi-docs/lib/theme/ApiExplorer/Body/index.js if ( (contentType === "multipart/form-data" || contentType === "application/x-www-form-urlencoded") && schema?.type === "object" ) { // Renders form fields from schema.properties } ``` Because `AccessTokenRequestV1` uses `oneOf` without a top-level `type: object`, this condition fails. The component falls through to the default empty editor path. ## 2. Documentation — Body → Schema tab **Expected:** `grant_type` visible as a required body field at the top level. **Actual:** The Schema tab shows: - A `oneOf` badge - Tabs for `ClientCredentialsGrantRequestV1` and `PasswordGrantRequestV1` - `grant_type` only visible **inside** a variant tab, after `allOf` merge **Root cause:** The theme's `Schema` component renders top-level `oneOf` as variant tabs. There is no `discriminator` on `grant_type`, so the UI does not treat it as the field that selects between grant variants. Inside each tab, `allOf` merge does preserve `grant_type` with the `required` badge — but it is nested and easy to miss. ## 3. Documentation — Body → Example tabs **Expected / Actual:** Example tabs (`ClientCredentialsGrantRequestV1`, `PasswordGrantRequestV1`) **do** show `grant_type` correctly. This is the one part that works as intended. --- ## Impact summary | Surface | `grant_type` required in spec? | Renders correctly? | Notes | |---------|-------------------------------|--------------------|-------| | OpenAPI YAML | Yes | N/A | Source of truth is correct | | Headers section | N/A | Yes | 4 required headers render fine | | Body → Schema tab | Yes | Partial | Hidden inside `oneOf` tabs | | Body → Example tabs | Yes | Yes | Examples show correct payloads | | API playground body form | Yes | **No** | Empty editor; no input fields | --- ## Additional schema observations (for reviewers) These are separate from the rendering issue but worth noting during review: 1. **`grant_type` enum on each variant** includes both `client_credentials` and `password`, even on the `ClientCredentialsGrantRequestV1` variant. Tighter per-variant enums would be clearer. 2. **`expires_in` example vs description** — Example value `2591999` (~30 days) conflicts with description stating default is 30 minutes. 3. **`refresh_token` in password response** — Response schema includes `refresh_token` fields, but documentation states the endpoint does not support the `refresh_token` grant type. 4. **OAuth V2 token endpoint** uses the same `oneOf` + `allOf` pattern (`AccessTokenRequestV2`) and likely has the same rendering behavior. --- ## Recommended fixes ## Option A — OpenAPI schema change (recommended) Restructure `AccessTokenRequestV1` so the theme can render it as a flat object or discriminated union: **Approach 1: Add discriminator** ``` AccessTokenRequestV1: type: object required: - grant_type discriminator: propertyName: grant_type oneOf: - $ref: '#/components/schemas/ClientCredentialsGrantRequestV1' - $ref: '#/components/schemas/PasswordGrantRequestV1' ``` **Approach 2: Flatten to a single object** ``` AccessTokenRequestV1: type: object required: - grant_type properties: grant_type: type: string enum: [client_credentials, password] username: type: string password: type: string # Use x-conditionally-required or description to document # that username/password are required when grant_type=password ``` **Pros:** Fixes both docs Schema tab and API playground form (with Approach 2 or discriminator + theme support). **Cons:** Requires OpenAPI change and regen of API docs (`npm run gen-api-docs`). ## Option B — Theme customization Customize `@theme/ApiExplorer/Body` to detect `oneOf` / `allOf` schemas for form-urlencoded content types, merge variants, and render the union of properties (with `grant_type` always visible). **Pros:** Fixes playground without changing API contract modeling. **Cons:** More complex theme maintenance; Schema tab may still show nested `oneOf` unless Schema component is also customized. ## Option C — Documentation workaround (no code change) Add a callout on the OAuth V1 token page directing integrators to the **Example** tabs for body field reference, and note that the playground body form is not supported for this endpoint. **Pros:** Immediate, zero engineering. **Cons:** Does not fix the playground; poor integrator experience. --- ## Suggested review questions 1. Should we fix this at the **OpenAPI spec level** (Option A), **theme level** (Option B), or both? 2. Is flattening the request body schema acceptable, or must we preserve strict `oneOf` per grant type? 3. Should the same fix be applied to **OAuth V2** (`AccessTokenRequestV2`), which uses the same pattern? 4. Is the API playground expected to support form-urlencoded `oneOf` bodies, or is it acceptable to document this as a known limitation? 5. Should we address the additional schema inconsistencies (`expires_in` example, `refresh_token` in response, enum breadth) in the same change? --- ## References | Item | Location | |------|----------| | OpenAPI endpoint definition | `openapi/candescent-di-api.yaml` — `/v1/oauth/token` | | Request schemas | `AccessTokenRequestV1`, `TokenRequestBaseV1`, `ClientCredentialsGrantRequestV1`, `PasswordGrantRequestV1` | | Generated docs page | `docs/api/generated/create-access-token-v-1.api.mdx` | | Custom RequestSchema theme | `src/theme/RequestSchema/index.tsx` | | Theme Body component (upstream) | `node_modules/docusaurus-theme-openapi-docs/lib/theme/ApiExplorer/Body/index.js` | | Theme Schema component (upstream) | `node_modules/docusaurus-theme-openapi-docs/lib/theme/Schema/index.js` | --- ## Appendix: Example requests ## Client credentials ``` POST /v1/oauth/token Authorization: Basic di_tid: f8187c63-678f-4f0c-9263-46723794661a di_fiid: 00016 Content-Type: application/x-www-form-urlencoded grant_type=client_credentials ``` ## Password (retail only) ``` POST /v1/oauth/token Authorization: Basic di_tid: f8187c63-678f-4f0c-9263-46723794661a di_fiid: 00016 Content-Type: application/x-www-form-urlencoded grant_type=password&username=userTest&password=Test@123 ``` --- ## Quick Start Get up and running with the Candescent API (/guides/getting-started/api-overview) within minutes. ## Prerequisites Before you begin, you'll need access to the Candescent Developer Console (/guides/Developer%20Console/overview) to obtain your API credentials. ## For Financial Institution Developers 1. Request access to the Developer Console through your FI administrator. 2. Your FI admin or Candescent Support will grant access to the console. 3. Once approved, log in to the Developer Console to obtain your credentials. ## Step 1: Obtain Your API Credentials 1. Log in to the Candescent Developer Console (https://console.candescent.com). 2. Navigate to your application settings (/guides/Developer%20Console/managing-applications-and-api-credentials). 3. Locate your **Shared Key** and **Secret Key**. 4. Copy and store these credentials securely. [warning] Never share your **Secret Key** or commit it to version control. Use environment variables to store sensitive credentials. ## Step 2: Obtain an Access Token Candescent APIs use OAuth 2.0 for authentication. Exchange your **Shared Key** and **Secret Key** for an access token. [note] OAuth 2.0 token requests use the standard parameter names `client_id` and `client_secret` (your Shared Key and Secret Key map to those values—for example in the request body or HTTP Basic Authentication). [important] For server-to-server API calls, you must use `grant_type=client_credentials` in your token request. This ensures the generated access token has the correct permissions for backend integrations. See the Create Token API (/api/generated/create-access-token-v-2/) for complete request and response details and code examples. [tip] Access tokens typically expire after one hour. Implement token refresh logic in your application to maintain uninterrupted access. ## Step 3: Make Your First API Request Use the access token to make authenticated API calls. Include the token in the `Authorization` header with the `Bearer` prefix, along with the required headers listed below. Try the List Accounts API (/api/generated/list-accounts-v-1) to retrieve account information for a customer. ## Step 4: Explore the API Now that you've made your first successful request, explore our API documentation: - Authentication API (/api/generated/o-auth-v-2/) - Token management and OAuth flows - Accounts API (/api/generated/accounts/) - Account information and balances - Transfers API (/api/generated/transfers/) - Account transfer, loan payments, recipient, scheduled transfers - User Alert Preferences API (/api/generated/user-preferences/) - User notification preferences ## Environment URLs | Environment | Base URL | |-------------|----------| | Sandbox | `https://api.sandbox.candescent.com` | | Stage | `https://api.stage.candescent.com` | | Production | `https://api.candescent.com` | [note] Start with the stage environment for development and testing. Contact your Candescent representative for production access. ## Need Help? - Review the Error Codes Reference (/guides/getting-started/error-codes) for API error handling. - Review the OIDC Integration Overview (/guides/OIDC%20Integration/overview) for SSO implementation. - Visit the API Reference (/api/generated/candescent-di-api/) for complete endpoint documentation. - Contact support at support@candescent.com. --- # OIDC INTEGRATION ## FAQ & Troubleshooting ## Getting Started - **How do I begin an OIDC integration project?** - You will be assigned a Candescent Integration Project Manager via Marketplace. Your PM is your primary contact for the duration of the certification of your integration. - **Can I test my integration before contacting Candescent?** - Yes! Use the OIDC Toolkit (/guides/OIDC%20Integration/local-development) to build and test your integration locally. The toolkit simulates Candescent's OIDC flow with the same endpoints and token format. - **What information do I need to provide?** - Complete the Setup Checklist (/guides/OIDC%20Integration/setup-checklist) with your application details, contacts, and redirect URIs. - Any information on your solution, or that you feel is relevant to the integration. - **What is the typical integration process?** - (Optional) Local development using the OIDC Toolkit (/guides/OIDC%20Integration/local-development) - Initialization - Candescent PM provides relevant documentation, and answers any initial questions. Developer will then complete and return the Setup Checklist (/guides/OIDC%20Integration/setup-checklist) - Once the partner provides a completed Setup Checklist (/guides/OIDC%20Integration/setup-checklist), the Candescent team will install the connection in our internal QA site for initial testing. - Initial QA validation using Candescent's standard test API app - Registration of your application and environments - Configuration of trust, security, and endpoints - Integration testing in FI environments - Certification and go-live ## Technical Basics - **Which endpoints do I use?** - Authorization endpoint: FI's branded domain (provided by your PM) - Token endpoint: api.candescent.com (centralized, backend only) - **How do I get JWKS files?** - Your assigned PM will provide JWKS files for each environment. There is no public JWKS URI. - **What claims are supported?** - Only standard OIDC claims (`sub`, `iss`, `exp`, `iat`, `nonce`, `preferred_username`, `given_name`, `family_name`, `birthday`, `email`, `phone_number`, `auth_time`) - **Is there a UserInfo endpoint?** - There is no standard OIDC `/userinfo` endpoint. All standard claims are included in the ID token. If you need additional user data, you can use the optional Institution-users endpoint (/guides/OIDC%20Integration/technical-reference/#institution-users-endpoint-optional). ## Common Issues & Solutions - **Invalid `redirect_uri`:** - Ensure the URI is registered, uses HTTPS, and matches exactly (no wildcards, no trailing slash differences). - **State validation failed:** - Store and validate the state parameter for CSRF protection. - **Authorization code expired:** - Exchange the code immediately (valid for 60–120 seconds). - **Client authentication failed:** - Verify credentials encoding and use `client_secret_basic` or `client_secret_post`. - **Token signature validation fails:** - Ensure you are using the correct JWKS file for the environment and that it is up to date. - **JWKS key rotation:** - Your PM will notify you and provide updated files when keys rotate. ## Critical Timeouts - Authorization code: 60–120 seconds - ID token: 5 minutes (extract claims immediately) - Access token: ~30 minutes - Session: ≤30 minutes ## OIDC Toolkit Questions - **Where do I get the OIDC Toolkit?** - Clone from GitHub: `git clone https://github.com/candescent-dev/oidc-sso-toolkit.git` - Or use the pre-built Docker image: `docker pull ghcr.io/candescent-dev/oidc-sso-toolkit:latest` - **Do I need Docker to run the toolkit?** - No. You can run it natively with Node.js 20+ for development. Docker is an optional alternative for quick testing without installing Node.js. - **Why do my toolkit credentials expire after 15 minutes?** - This is by design. The toolkit auto-generates new credentials to simulate real-world credential rotation. The page refreshes automatically. - **Can I change the toolkit ports?** - Yes. Edit `sample-web-app/config.json` to change frontend (default 8000) and backend (default 9000) ports. - **How do I validate my integration with the toolkit?** - Use the built-in OIDC Validator page to run automated E2E tests. See the Local Development Guide (/guides/OIDC%20Integration/local-development#automated-validation). ## Tips for Success - Test locally with the OIDC Toolkit (/guides/OIDC%20Integration/local-development) before connecting to Candescent environments - Extract ID token claims immediately after token exchange - Store credentials securely (never in code or logs) - Use HTTPS everywhere - Validate state and nonce parameters - Exchange authorization code for tokens immediately ## Contact & Support For questions or support, reach out to your assigned Candescent Integration PM via Marketplace. Your PM will provide all necessary materials, guidance, and troubleshooting assistance. ## References - OpenID Connect Core Spec (https://openid.net/specs/openid-connect-core-1_0.html) - OAuth 2.0 Framework (RFC 6749) (https://tools.ietf.org/html/rfc6749) --- ## Local Development with the OIDC Toolkit ## Overview The OIDC Toolkit provides a local development environment for building and testing OpenID Connect (OIDC) Single Sign-On integrations. It simulates the Candescent platform's OIDC flow, allowing you to develop and validate your integration before connecting to QA or production environments. To setup the OIDC Toolkit, refer to the instructions in the README (https://github.com/candescent-dev/oidc-sso-toolkit/blob/main/README.md) file. ## What You Can Do - Set up a complete OIDC Identity Provider locally. - Generate test client credentials (`client_id`, `client_secret`). - Download metadata and JWK files compatible with Candescent's format. - Execute the full authorization code flow. - Validate ID tokens and extract user claims. - Run automated E2E tests to verify your integration. :::tip When to Use the Toolkit Use the OIDC Toolkit during initial development to build and debug your OIDC client implementation. Once your integration works locally, proceed to QA validation (/guides/OIDC%20Integration/overview#1-initial-qa-validation) with your Candescent PM. ::: ## Using the Toolkit ## 1. Generate Client Credentials When the homepage loads, the toolkit automatically generates: | Field | Description | |-------|-------------| | **Client ID** | Public identifier for your OIDC client | | **Client Secret** | Secret key for token exchange | :::warning Credential Expiration Credentials expire after **15 minutes** and auto-regenerate. The page refreshes automatically. ::: ## 2. Download Configuration Files Click the buttons to download: | File | Purpose | Use In Your App | |------|---------|-----------------| | **Metadata** | OIDC discovery document | Configure endpoints, scopes | | **JWK** | RSA public key | Validate ID token signatures | ## 3. Configure Your Integration Enter the required parameters: | Parameter | Description | Example | |-----------|-------------|---------| | **Init URL** | Your app's SSO entry point | `http://localhost:3000/sso/init` | | **Callback Host** | OAuth redirect URI base | `http://localhost:3000/callback` | **Example Configuration:** If your application runs on `localhost:3000`, you might configure: ``` Init URL: http://localhost:3000/auth/sso/start Callback Host: http://localhost:3000/auth/callback ``` :::tip Testing with the Toolkit For quick testing without a real app, you can use the toolkit's own URLs: - **Init URL:** `http://localhost:8000` - **Callback Host:** `http://localhost:8000` This lets you test the OIDC flow end-to-end without building your own callback handler first. ::: ## 4. Choose Display Mode | Mode | Use Case | |------|----------| | **Open in Iframe** | Embedded authentication experience | | **Open in new tab** | Standard redirect-based flow | For Iframe mode, also configure: - **Unique ID** - Identifies the Iframe session. - **Display Width (%)** - Controls Iframe width. - **Permissions** - Camera/microphone access (if needed). ## 5. Execute the OIDC Flow 1. Click **Submit** to save your configuration. 2. Click **Start OIDC SSO** to initiate the flow. 3. The toolkit simulates user authentication. 4. Your callback receives the authorization code. 5. Exchange the code for tokens. --------|----------|-------------| | `client_id` | Yes | From toolkit homepage | | `response_type` | Yes | Must be `code` | | `scope` | Yes | Must include `openid` | | `redirect_uri` | Yes | Your callback URL | | `state` | Recommended | CSRF protection token | **Example:** ``` http://localhost:9000/api/auth/authorize? client_id=YOUR_CLIENT_ID &response_type=code &scope=openid &redirect_uri=https://yourapp.com/callback &state=random_state_value ``` ## Token Endpoint ``` POST http://localhost:9000/api/auth/token ``` **Headers:** ``` Authorization: Basic Content-Type: application/json ``` **Body:** ``` { "code": "AUTHORIZATION_CODE" } ``` **Response:** ``` { "id_token": "eyJhbGciOiJSUzI1NiIs...", "access_token": "abc123...", "token_type": "Bearer", "expires_in": 900 } ``` :::note Production Format In production, the token endpoint uses `application/x-www-form-urlencoded` format instead of JSON. See the Technical Reference (/guides/OIDC%20Integration/technical-reference#token-exchange) for production examples. ::: --- ## Validating Your Integration ## Manual Validation 1. Decode your ID token at jwt.io (https://jwt.io). 2. Verify the signature using the downloaded JWK. 3. Check all required claims are present and valid. ## Automated Validation The toolkit includes E2E tests to validate your integration: 1. Complete steps 1-4 above (configure and run the OIDC flow). 2. Navigate to the **OIDC Validator** page (link in top-right). 3. Click **Run Validator**. 4. Review the test results. **Available Reports:** | Report | Format | Purpose | |--------|--------|---------| | `e2e-report.html` | HTML | Human-readable test results | | `jest-e2e.xml` | JUnit XML | CI/CD integration | ## Export Configuration After successful validation: 1. Click **Publish OIDC Setting**. 2. Download `oidcConfig.json`. 3. Use this configuration as a reference when connecting to Candescent environments. --- ## Configuration Reference ## Port Configuration Edit `sample-web-app/config.json`: ``` { "frontendPort": 8000, "backendPort": 9000 } ``` ## Token Expiration Edit `sample-web-app/backend/src/ssoConfig/sso-config.json`: ``` { "auth_code_expires_in": 900, "access_token_expires_in": 900, "id_token_expires_in": 900 } ``` Values are in seconds (900 = 15 minutes). --- ## Differences from Production The toolkit simulates Candescent's OIDC flow, but some differences exist: | Aspect | Toolkit | Production | |--------|---------|------------| | Authorization URL | `localhost:9000/api/auth/authorize` | FI-specific domain | | Token URL | `localhost:9000/api/auth/token` | `api.candescent.com/.../token` | | Token Request Format | JSON body | `application/x-www-form-urlencoded` | | User Authentication | Simulated (automatic) | Real FI login page | | Credentials | Auto-generated, 15-min expiry | PM-provided, 90-day rotation | | JWKS | Downloaded file | PM-provided file | :::info Transition to Production Once your integration works with the toolkit, contact your Candescent PM to begin QA validation (/guides/OIDC%20Integration/overview#1-initial-qa-validation) with production-like credentials and endpoints. ::: --- ## Troubleshooting | Issue | Cause | Solution | |-------|-------|----------| | Credentials expired | 15-minute TTL | Refresh the page or wait for auto-refresh | | Port already in use | Another service running | Edit `sample-web-app/config.json` to change ports | | Token validation fails | JWK mismatch | Re-download JWK from toolkit | | CORS errors | Frontend/backend port mismatch | Ensure both are running on configured ports | | Docker pull unauthorized | Authentication required | Log in to GitHub Container Registry: `docker login ghcr.io -u YOUR_GITHUB_USERNAME` | | Docker container won't start | Port conflict | Stop other services on ports 8000/9000 or use different ports | --- ## Next Steps After validating your integration locally: 1. **Contact your PM** - Request QA environment access. 2. **Complete the Setup Checklist (/guides/OIDC%20Integration/setup-checklist)** - Provide application details. 3. **Begin QA testing** - Validate with real Candescent endpoints. 4. **Proceed to certification** - Complete FI environment testing. --- ## References - Technical Reference (/guides/OIDC%20Integration/technical-reference) - Full OIDC specification details - FAQ & Troubleshooting (/guides/OIDC%20Integration/faq) - Common questions and issues - OpenID Connect Core Spec (https://openid.net/specs/openid-connect-core-1_0.html) - OAuth 2.0 Framework (RFC 6749) (https://tools.ietf.org/html/rfc6749) --- ## Integration Overview ## Purpose This guide explains the process Marketplace Partners follow to complete an OIDC integration project with Candescent Digital Banking, from kickoff to certification. It is tailored for fintechs integrating their solutions with multiple financial institutions (FIs) via Candescent's platform. ## Project Kickoff - Marketplace Partners are assigned a Candescent Integration Project Manager (PM) via Marketplace. - Initial QA validation testing is required before any FI environment installation. - Your PM will provide all necessary materials, including JWKS files and endpoint details. ## Step-by-Step Integration Process ## 0. Local Development (Optional but Recommended) (/guides/OIDC%20Integration/local-development) Before connecting to Candescent environments, you can build and test your OIDC integration locally using the **OIDC Toolkit**: - Simulate the complete authorization code flow on your machine - Generate test credentials and validate token handling - Debug your implementation without external dependencies - Run automated E2E tests to verify your integration See the Local Development Guide for setup instructions. [tip] Local development is optional but highly recommended. It allows you to iterate quickly and arrive at QA validation with a working implementation. ## 1. Initial QA Validation - All integrations begin with QA testing using Candescent's standard test API application in the QA environment. - Partners do not need to onboard their own API application until after QA validation is complete. - Your PM will guide you through the QA process and provide access to the test environment. ## 2. Register Application (Post-QA) - After successful QA validation, partners provide: - Application name and description - Purpose and use case - Primary business and technical contacts - Expected launch timeline - List of authorized callback URLs (redirect URIs) for each environment (Stage, Production) ## 3. Configure Trust & Exchange - Register exact redirect URIs (HTTPS only, no wildcards). - Configure authentication using `client_secret_basic` or `client_secret_post`. - Set up state and nonce parameters for security. - Store credentials in a secure secrets management system. ## 4. Integration Testing in FI Environments - After registration, your PM will provide: - FI-specific authorization endpoint URLs - Centralized token endpoint URLs - JWKS files for each environment - Client credentials (`client_id` and `client_secret`) - Complete integration testing in each FI environment as directed by your PM. - Validate token exchanges, session management, and claim extraction per specification. ## 5. Certification & Go-Live - Upon successful testing, your integration will be certified for production use. - Your PM will coordinate go-live activities and provide ongoing support. ## Checklist for Marketplace Partners - Technical knowledge of OIDC/OAuth 2.0 and Authorization Code Flow - Secure infrastructure and secrets management - Ability to perform server-side HTTP requests and JWT validation - Developer Console (/guides/Developer%20Console/overview) access (as provided by PM) - Prepared to securely store credentials and JWKS files - (Recommended) Completed local development testing (/guides/OIDC%20Integration/local-development) with the OIDC Toolkit ## Contacts & Support For questions or support, reach out to your assigned Candescent Integration PM via Marketplace. Your PM is your primary point of contact for all integration-related matters. ## References - OpenID Connect Core Spec (https://openid.net/specs/openid-connect-core-1_0.html) - OAuth 2.0 Framework (RFC 6749) (https://tools.ietf.org/html/rfc6749) --- ## Setup Checklist Please review and complete the following form to provide all necessary information for your OIDC integration setup with Candescent Digital Banking. :::tip Before You Begin We recommend testing your integration locally using the OIDC Toolkit (/guides/OIDC%20Integration/local-development) before completing this checklist. This helps ensure your URLs and callback configurations are working correctly. ::: ## Required OIDC Setup Information ## Initialization URLs - List of initialization URLs. These are the URLs we target when a user attempts an SSO. Provide URLs for QA, Stage, Production, if applicable: - QA: - Stage: - Production: - All URLs must be exact HTTPS addresses (no wildcards) ## Redirect/Callback Host to Whitelist - Provide the domain of your callback/redirect URL(s): - This is so we can whitelist those domains to allow traffic. Please return this completed form to your assigned Candescent Integration PM. --- ## Technical Specification ## Introduction This document provides technical specifications for Marketplace Partners integrating with Candescent Digital Banking's OIDC SSO solution. It describes the architecture, endpoints, supported features, limitations, and requirements for partner-developed solutions. ## Integration Model - **Identity Provider (IdP):** Candescent Digital Banking - **Relying Party (RP):** Partner application or FI application - **Dual-Domain Architecture:** - **Authorization Endpoint:** FI's branded domain (user-facing) - **Token Endpoint:** Centralized at api.candescent.com (backend only) ## Audience Types This specification supports two integration audiences: | Audience | Description | Authorization Endpoint | |----------|-------------|----------------------| | **Financial Institution (FI)** | Direct integration for a single institution | Single, known FI domain | | **Marketplace Partner** | Fintech serving multiple FIs | Dynamic, based on originating FI | ## Multi-FI Partner Integration Marketplace Partners who offer OIDC SSO to multiple Financial Institutions must handle dynamic authorization endpoint routing. Since each FI has its own branded authorization domain, partners need to: 1. **Identify the originating FI** when a user initiates SSO 2. **Route to the correct authorization endpoint** for that specific FI ## How Partners Identify the FI When a user accesses your partner application via SSO, you need to determine which FI they belong to. Common methods include: | Method | Description | Example | |--------|-------------|---------| | **Query Parameter** | FI identifier passed in the SSO launch URL | `https://partner.com/sso?fi=acme_bank` | | **Subdomain** | FI-specific subdomain on your platform | `acmebank.partner.com` | | **Path Parameter** | FI identifier in the URL path | `https://partner.com/fi/acme_bank/sso` | | **Session Context** | FI determined from prior user selection | User selected FI from dropdown | ## Authorization Endpoint Routing Once you identify the FI, construct the authorization endpoint URL using the FI's specific domain: ``` https:// [tip] Store the FI identifier in the `state` parameter to maintain context through the OAuth flow. This allows you to associate the callback with the correct FI configuration. ## Token Endpoint (Centralized) Unlike authorization endpoints, the **token endpoint is centralized** for all FIs: - **Stage:** `https://api.stage.candescent.com/oauth2/v1/token` - **Production:** `https://api.candescent.com/oauth2/v1/token` Your partner application uses the same token endpoint regardless of which FI the user belongs to. ## Token Exchange ## Request ``` curl -X POST 'https://api.stage.candescent.com/oauth2/v1/token' \ -H 'Authorization: Basic ## Critical Timeouts - Authorization code: 60–120 seconds - ID token: 5 minutes - Access token: ~30 minutes - Session: ≤30 minutes ## Local Testing with the OIDC Toolkit Before testing with Candescent environments, you can validate your implementation locally using the **OIDC Toolkit**. The toolkit simulates the complete OIDC flow with the same endpoints, claims, and token format used in production. ## Quick Start **Option 1: Native Setup (Recommended for Development)** ``` ## Clone the toolkit git clone https://github.com/candescent-dev/oidc-sso-toolkit.git cd oidc-sso-toolkit ## Start backend (Terminal 1) cd sample-web-app/backend npm install npm run start:dev # Development mode with hot-reload ## Start frontend (Terminal 2) cd sample-web-app/frontend npm install npm start # Starts Vite dev server on port 8000 ## Open http://localhost:8000 ``` :::note Default Certificates Default development certificates are included for convenience. These are safe for local testing but should not be used in production or QA environments. ::: **Option 2: Docker (Quick Testing)** ``` ## Pull and run pre-built image docker pull ghcr.io/candescent-dev/oidc-sso-toolkit:latest docker run -p 8000:8000 -p 9000:9000 ghcr.io/candescent-dev/oidc-sso-toolkit:latest ## Open http://localhost:8000 ``` :::note Authentication If you encounter an "unauthorized" error when pulling the image, authenticate with GitHub Container Registry: ``` docker login ghcr.io -u YOUR_GITHUB_USERNAME ``` Use a GitHub Personal Access Token (PAT) with `read:packages` permission. ::: ## What the Toolkit Provides | Feature | Toolkit | Production | |---------|---------|------------| | Authorization endpoint | `localhost:9000/api/auth/authorize` | FI-specific domain | | Token endpoint | `localhost:9000/api/auth/token` | `api.candescent.com` | | Client credentials | Auto-generated | PM-provided | | JWK for validation | Downloadable | PM-provided | | ID token claims | Same as production | Same | [tip] The toolkit generates ID tokens with identical claims to production, making it ideal for testing your token parsing and validation logic. For complete setup instructions, see the Local Development Guide (/guides/OIDC%20Integration/local-development). ## Testing Your Credentials Verify your credentials are correctly configured by making a test token request: ``` ## Generate Base64 credentials echo -n "your_client_id:your_client_secret" | base64 ## Test authentication (use an invalid code to test credentials only) curl -X POST 'https://api.stage.candescent.com/oauth2/v1/token' \ -H 'Authorization: Basic ' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code&code=TEST' ``` | Response | Meaning | |----------|---------| | `invalid_grant` | ✅ Credentials valid, code was invalid (expected) | | `invalid_client` | ❌ Credentials incorrect | ## Python Implementation A complete Flask implementation for the OIDC callback handler: ``` from flask import Flask, redirect, request, session, url_for from jwcrypto import jwk, jwt app = Flask(__name__) app.secret_key = secrets.token_hex(32) ## Configuration - replace with your values CLIENT_ID = "your_client_id" CLIENT_SECRET = "your_client_secret" REDIRECT_URI = "https://yourapp.com/callback" TOKEN_ENDPOINT = "https://api.stage.candescent.com/oauth2/v1/token" ISSUER = "https://www.digitalinsight.com" ## Load JWKS from file provided by your PM with open("jwks.json") as f: JWKS = jwk.JWKSet.from_json(f.read()) @app.route("/login") def login(): """Redirect user to FI authorization endpoint.""" state = secrets.token_urlsafe(32) nonce = secrets.token_urlsafe(32) session["oauth_state"] = state session["oauth_nonce"] = nonce # Get FI-specific authorization endpoint (from your configuration) auth_endpoint = "https://online.acmebank.com/usr-engage-olb/beta/v1/tpv-sso-authorize" params = { "client_id": CLIENT_ID, "redirect_uri": REDIRECT_URI, "response_type": "code", "scope": "openid profile email", "state": state, "nonce": nonce } return redirect(f"{auth_endpoint}?{'&'.join(f'{k}={v}' for k, v in params.items())}") @app.route("/callback") def callback(): """Handle the authorization callback.""" # Validate state if request.args.get("state") != session.get("oauth_state"): return "State mismatch", 400 code = request.args.get("code") if not code: return "Missing authorization code", 400 # Exchange code for tokens credentials = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode() response = requests.post( TOKEN_ENDPOINT, headers={ "Authorization": f"Basic {credentials}", "Content-Type": "application/x-www-form-urlencoded" }, data={ "grant_type": "authorization_code", "code": code, "redirect_uri": REDIRECT_URI } ) if not response.ok: return f"Token exchange failed: {response.text}", 400 tokens = response.json() id_token = tokens["id_token"] # Validate and decode ID token try: token = jwt.JWT(key=JWKS, jwt=id_token) claims = json.loads(token.claims) # Validate claims if claims["iss"] != ISSUER: return "Invalid issuer", 400 if claims["nonce"] != session.get("oauth_nonce"): return "Invalid nonce", 400 # Store user info in session session["user"] = { "sub": claims["sub"], "name": f"{claims.get('given_name', '')} {claims.get('family_name', '')}", "email": claims.get("email") } return redirect(url_for("dashboard")) except Exception as e: return f"Token validation failed: {e}", 400 @app.route("/dashboard") def dashboard(): if "user" not in session: return redirect(url_for("login")) return f"Welcome, {session['user']['name']}!" ``` **Required packages:** ``` pip install flask requests jwcrypto ``` ## Troubleshooting & Support - Invalid `redirect_uri`: Ensure exact match and HTTPS - State validation failed: Store and validate state parameter - Authorization code expired: Exchange immediately (60–120 seconds) - Client authentication failed: Verify credentials encoding - Token signature validation fails: Ensure correct JWKS file and environment - JWKS key rotation: PM will notify and provide updated files For questions or support, contact your assigned Candescent Integration PM. ## References - OpenID Connect Core Spec (https://openid.net/specs/openid-connect-core-1_0.html) - OAuth 2.0 Framework (RFC 6749) (https://tools.ietf.org/html/rfc6749) --- # API REFERENCE SUMMARY The Candescent Digital Banking API provides RESTful endpoints for: ## AUTHENTICATION OAuth 2.0 token management: client credentials, password grant, authorization code, refresh, revocation. Endpoint: https://docs.candescent.com/api/generated/authentication/ ## ACCOUNTS Account details, balances, transaction history, and banking images. Endpoint: https://docs.candescent.com/api/generated/accounts/ ## BUSINESS BANKING Business onboarding, registration, entitlements, and business profile management. Endpoint: https://docs.candescent.com/api/generated/business-banking/ ## ALERT CONFIGURATION Configure alert types, message templates, and institution settings. Endpoint: https://docs.candescent.com/api/generated/alert-configuration/ ## ALERT DELIVERY Trigger alerts and track delivery history. Endpoint: https://docs.candescent.com/api/generated/alert-delivery/ ## ALERT PREFERENCES Customer alert thresholds and notification preferences. Endpoint: https://docs.candescent.com/api/generated/alert-preferences/ ## NOTIFICATION CHANNELS Register devices, emails, and phone numbers for notifications. Endpoint: https://docs.candescent.com/api/generated/notification-channels/ ## CUSTOMER MANAGEMENT Customer profiles, registration, password reset, and MFA. Endpoint: https://docs.candescent.com/api/generated/customer-management/ ## CUSTOMER CAMPAIGNS User segmentation, experience groups, and promotional targeting. Endpoint: https://docs.candescent.com/api/generated/customer-campaigns/ ## MONEY MOVEMENT Recipients and transfers: one-time, recurring, scheduled. Endpoint: https://docs.candescent.com/api/generated/money-movement/ ## DOCUMENTS AND PREFERENCES Disclosures, e-statements, and compliance management. Endpoint: https://docs.candescent.com/api/generated/documents-and-preferences/ ## MX Account aggregation, PFM, and financial insights via MX integration. Endpoint: https://docs.candescent.com/api/generated/mx/ --- # GLOSSARY | Term | Definition | |------|------------| | FI | Financial Institution - Banks and credit unions | | Marketplace Partner | Fintech integrating with Candescent via the Marketplace | | Digital Banking | Online and mobile banking capabilities | | OIDC | OpenID Connect - Authentication protocol for SSO | | OAuth 2.0 | Authorization framework for secure API access | | JWT | JSON Web Token - Secure token format | | JWKS | JSON Web Key Set - Public keys for verification | | MFA | Multi-Factor Authentication | | PFM | Personal Finance Management | --- # SUPPORT - Email: support@candescent.com - Partner Portal: https://marketplace.candescent.com - Developer Console: https://console.candescent.com --- Generated: 2026-10-29T07:42:30.124Z This file provides complete documentation content for LLM consumption.