CircleBlack

CircleBlack is a household-based data sync integration using OAuth 2.0 with SAML authentication.

Overview

Attribute	Value
Integration Type	Data Sync (Read-only)
Authentication	OAuth 2.0 with SAML 2.0 assertion
Data Flow	CircleBlack → RightCapital (inbound only)
Owner	Tingsong Xu

Data Structure

Household
└── Clients (with relationship info)
    └── Accounts
        └── Allocations (Holdings)

Authentication Flow

1. Generate SAML 2.0 assertion (Subject: advisor ID)
2. Sign assertion using X509 certificate (RSA-SHA256)
3. Exchange signed assertion for OAuth access token
4. Use access token for API calls

API Endpoints

Endpoint	Purpose
POST /auth/token	OAuth token exchange with SAML
GET /households	List all households
GET /households/{id}	Get household with clients and accounts

Security Matching

Securities matched by 9-character CUSIP code.

Code Locations

Component	Path
Connector	retail-api/app/Integrations/CircleBlack/Connector.php
Integrator	retail-api/app/Integrations/CircleBlack/Integrator.php
Models	retail-api/app/Integrations/CircleBlack/Models/

Common Issues

User Has No Consent

Symptom: Authentication fails with “user has no consent”

Solution: Advisor needs to authorize RightCapital in CircleBlack settings