Camino (Identity + CRM)

The identity hub of the RBS ecosystem. OAuth2 IdP, multi-tenant organization primitives, and the CRM event sink where every other app reports activity.

URL: camino.redbroomsoftware.comStatus: LIVE Tier: T1 SDK: @r-bsoftware/ecosystem-sdk — RBSAuth, generateState, validateState, createSubscriptionClient, registerWithEcosystem, APP_REGISTRY

What you can integrate

• Single sign-on for your app via Camino's OAuth2 + PKCE authorization server (21 registered clients today — one per ecosystem app)
• Subscription + feature gating — check tier entitlements before serving paid features, surface upsell recommendations
• Customer activity ingestion — emit activity.logged, customer.created, sale.completed, etc. and have them land on a unified CRM timeline for the end customer
• Org-to-tenant resolution — map your internal tenant IDs to a canonical Camino organization
• Embed a lead-capture widget via /embed/lead-form.js

Authentication

Two auth modes for partners:

• User-facing: OAuth2 with PKCE. See Auth for the full authorize → token → userinfo flow.
• Server-to-server: API key (Authorization: Bearer <key>). Issued per app from the Camino admin console.

Inbound webhooks from partner apps are signed HMAC-SHA256 — see Webhooks.

Endpoints

Method	Path
GET	/api/analytics/conversion-funnel
POST	/api/auth/reset-password
GET, POST	/api/chatbot/query
POST	/api/checkout/bundle/pricing
GET	/api/checkout/bundle/products
POST	/api/checkout/bundle/session
GET, POST	/api/checkout/bundle/session/:id
GET	/api/checkout/bundle/stats
PATCH	/api/cobranza/:id
POST	/api/communications/send

300 total — 173 admin/cron/internal (hidden) — +117 more primary endpoints not shown. Source: src/routes/api/**/+server.{ts,js} in the camino repo.

Events emitted

Event	Receivers	Description
account.deletion_requested	colectiva	A user has submitted an account deletion request (soft-delete). Subscribers mark local user records with deletion_requested_at and notify their local operators — they do NOT auto-delete data. Actual anonymization is gated behind a separate 'account.deletion_approved' event (Phase 4).
brain.signal	camino, colectiva	Cross-brain intelligence signal. Emitted by Camino (marketing/fiscal intelligence) and Colectiva (operational/financial intelligence) to share insights bidirectionally. Carries a typed signal with severity, priority, and actionable context.
catalog.sync.completed	comal	Camino → Comal callback when a TikTok catalog sync succeeds for a Comal store product. Comal updates products.tiktok_product_id + tiktok_synced_at.
catalog.sync.failed	comal	Camino → Comal callback when a TikTok catalog sync fails. Comal surfaces the error to the merchant in the product list.
customer.created	camino, constanza, garita	A new customer/contact/third-party record was created — used for CRM sync, fiscal pre-registration, and cross-app contact linking.
customer.merged	agente, cosmos-pet, hoja, madriguera	Two duplicate customer records were merged in Camino — receiver apps update their local foreign keys to the canonical customer ID.
customer.updated	agente, colectiva, constanza, cosmos-pet, garita, hoja, madriguera	A customer/contact record was updated in Camino — receiver apps sync the changed fields to their local customer records for display and invoicing accuracy.
deal.billed	constanza	[auto-derived] deal.billed event
deal.commission_ready	colectiva	Camino has processed a deal billing record and calculated commission splits. Colectiva uses this to route payouts to developer/provider wallets. S125 Gap #18.
deal.won	agora	A deal was marked as won in Camino CRM — Agora creates or updates the associated matter/client record for the legal team.
insights.available	agente, cosmos-pet, hoja	Camino's AI engine generated new business insights for a tenant — receiver apps surface the insights in their dashboards for operator review.
lead.qualified	agora	A lead was qualified in Camino CRM — Agora receives the qualified lead to create a new matter intake for the legal team.
subscription.activated	agente, agora, camino, caracol, colectiva, comal, constanza, continua, cosmos-pet, garita, hoja, madriguera, mancha, patadas, plenura, rito, servilleta	A subscription plan has been activated for a tenant — all apps that gate features behind the subscription tier update their local tier state.
subscription.cancelled	agente, agora, camino, caracol, colectiva, comal, constanza, continua, cosmos-pet, garita, hoja, madriguera, mancha, patadas, plenura, rito, servilleta	A subscription has been cancelled — all apps that gate features behind the subscription tier update their local tier state to free/cancelled.
subscription.changed	agora, caracol, comal, cosmos-pet, hoja, madriguera, plenura, rito	A subscription plan has been upgraded or downgraded — receiver apps update their tier gates and feature access accordingly.
subscription.expired	comal, plenura	A subscription has expired (end of billing period, no renewal)
subscription.limit_approaching	agente, cosmos-pet, hoja, madriguera	A tenant's subscription usage is approaching the plan limit — Camino notifies subscriber apps to surface a plan-upgrade prompt to the tenant operator.
subscription.past_due	comal, plenura, rito	A tenant's subscription entered past_due state after a failed renewal — Camino dunning flow pauses feature access without cancelling. Receiver apps mark memberships or subscriptions past_due until payment is received.
subscription.payment_failed	agora, baul, camino, plenura, servilleta	A subscription payment attempt failed — receiver apps surface a payment-failed banner to the tenant operator and may restrict feature access.
subscription.payment_received	constanza	[auto-derived] subscription.payment_received event
subscription.pending_cancellation	agora, camino, plenura, servilleta	A subscription cancellation was scheduled for the end of the current billing period — receiver apps surface a notice that the subscription will end soon.
subscription.renewed	camino, constanza, mancha, plenura, servilleta	A subscription was successfully renewed for a new billing period — receiver apps update the subscription period end date and resume any paused features.
subscription.suspended	agente, caracol, cosmos-pet, madriguera	A subscription was suspended due to non-payment or compliance issue — Camino disables access until resolution. Receiver apps lock out the tenant and surface a suspension banner.
subscription.trial_expiring	colectiva, comal, hoja, plenura	A trial subscription is expiring soon — receiver apps surface an upgrade prompt to the tenant operator.
subscription.trial_started	colectiva, comal, hoja, plenura	A trial subscription was started — receiver apps activate trial-tier features for the new tenant.
team_member.created	constanza	A new team member was added to a workspace in Camino — Constanza pre-registers the employee for fiscal/payroll onboarding.
team_member.deactivated	constanza	A team member was deactivated in Camino — Constanza marks the employee as inactive and may trigger an IMSS baja process.
team_member.updated	constanza	A team member's record was updated in Camino — Constanza syncs the changed fields on the employee record.

Events consumed

Event	Senders	Description
activity.logged	agora, caracol, cosmos-pet, madriguera	A billable or tracked activity has been logged (time entry from Agora ghost timer, POS customer action in Caracol, vet/hotel log in Cosmos Pet or Madriguera) and sent to Camino for CRM activity tracking
appointment.completed	cosmos-pet, plenura	A therapy or veterinary appointment has been completed and paid
bank_package.generated	rito	Rito generated a bank financing package — Constanza pre-prepares fiscal structure for the loan; Camino logs the activity.
booking.completed	goodbay	A stay/booking has been completed at checkout — settlement signal (owner payout, RBS commission). PD-073 Slice 2 (S317): goodbay re-added as sender, now firing from /api/bookings/[id]/checkout. Camino receiver retains the Plenura-shape handler with source_app discriminator (S317 logistics.ts:20 guard — non-Plenura sourceApp ignored).
brain.signal	camino, colectiva	Cross-brain intelligence signal. Emitted by Camino (marketing/fiscal intelligence) and Colectiva (operational/financial intelligence) to share insights bidirectionally. Carries a typed signal with severity, priority, and actionable context.
capital_call.bulk_created	rito	A pro-rata capital call was issued to multiple investors simultaneously in Rito — Camino logs the batch for CRM activity.
caracol.invoice.stamped	caracol	A CFDI was stamped through Caracol's own PAC flow (not routed through Constanza). Distinct from cfdi.stamped which Constanza emits after stamping. Used for unified fiscal record + subscription metering.
caracol.order.created	caracol	A new order was created in Caracol POS — feeds Camino CRM order pipeline and activity feed
caracol.order.status_changed	caracol	Order status transition in Caracol POS (e.g., preparing → ready → delivered) — Camino mirrors for CRM timeline
caracol.shipment.created	caracol	A Skydropx shipment label was generated in Caracol — Camino records cost, applies markup, and bills the tenant. Also triggers WhatsApp tracking notification via Camino.
cfdi_global.stamped	caracol	Monthly factura global (CFDI Público en General) successfully stamped by the monthly-cfdi-publico cron. Distinct from caracol.invoice.stamped (per-sale) — carries batch context (period, salesIds) for downstream fiscal reconciliation and subscription metering.
cfdi.stamped	constanza	A CFDI invoice has been stamped by the SAT via Constanza — receiver apps attach the UUID to their local invoice record and update status.
cofepris.expiring	agente	An Agente COFEPRIS permit is expiring within 30 days — triggers WhatsApp alert and CRM activity log in Camino
cpi.investor_update_posted	colectiva	A CPI investor update was posted on a Colectiva offering — Camino sends email to each investor who purchased this offering.
cpi.purchased	colectiva	A CPI (Colectiva Participation Instrument) was purchased — Camino creates/updates contact with cpi_holder tag + logs purchase timeline; Constanza records sale for accounting.
cpi.transfer_completed	colectiva	A CPI secondary market transfer completed — Camino sends buyer receipt + seller sale confirmation emails.
customer.created	camino, caracol, comal, servilleta	A new customer/contact/third-party record was created — used for CRM sync, fiscal pre-registration, and cross-app contact linking.
customer.identified	mancha	A customer was identified during a transaction in Mancha (restaurant POS) — Camino creates or updates the CRM contact record with the transaction context for relationship tracking.
deadline.changed	agora	An existing legal deadline in Agora was updated (new date or description) — Camino mirrors for CRM timeline and reminder workflows
deadline.created	agora	A new legal deadline was set on a matter in Agora — Camino stores it for CRM visibility and deadline alerts
deal.created	rito	A new real estate deal was created in Rito — Camino CRM logs the activity; Constanza pre-registers fiscal structure for the deal.
deal.intelligence_generated	rito	Rito's proactive intelligence engine completed analysis on a deal — Camino CRM tags the deal with recommended strategy and asset class.
deal.status_changed	rito	A real estate deal's status transitioned to a new value in Rito — Camino mirrors for CRM pipeline. Distinct from deal.stage_changed (investor pipeline).
delivery.confirmed	baul	Delivery completed with proof of delivery (photos, signature)
demurrage.accumulating	agente	[auto-derived] demurrage.accumulating event
deposit.completed	baul	Cash deposit completed at bank with proof (photo of slip, GPS). Baul physical layer event. Triggers expense creation in Constanza and agreement reconciliation in Colectiva.
distribution.completed	colectiva	A participation distribution completed in Colectiva — Camino logs investor activity + sends confirmation email.
fiscal.anomaly_detected	constanza	Constanza AI detected an unusual pattern in an organization's financial data (z-score outlier, Benford violation, duplicate transaction, timing anomaly, etc.). Routed to Camino for CRM health alerts and to Colectiva so the Brain can factor fiscal anomalies into business intelligence.
fiscal.compliance_risk	constanza	Constanza identified a SAT compliance risk for an organization: missing declarations, RFC issues, expired CSD certificate, or overdue obligations. Routed to Camino so the CRM can surface the alert and prompt the tenant to take corrective action.
fiscal.health_score_updated	constanza	[auto-derived] fiscal.health_score_updated event
garita.property.type_changed	garita	[auto-derived] garita.property.type_changed event
handoff.completed	baul	Generic physical handoff completed with proof. Covers document delivery, product returns, sample collection, key handoff, equipment transfer. Baul physical layer event.
inventory.low	caracol, comal, hoja	A product inventory fell below the low-stock threshold — Colectiva records the alert for analytics; Camino logs it as a TenantIntelligence signal in organization_activity_log.
investor.created	rito	A new LP investor was created in Rito — Camino receives the contact for CRM sync.
investor.nda_signed	colectiva	An investor signed an NDA for a CPI offering in Colectiva — Camino creates/updates contact with investor tags + logs timeline event.
investor.updated	rito	An LP investor record was updated in Rito — Camino syncs CRM fields.
invoice.failed	(none declared)	An invoice payment failed — Camino records the failure on the cobranza receivable and may trigger a dunning follow-up.
invoice.paid	colectiva	An invoice was paid — Camino marks the cobranza receivable as paid and logs the payment event on the CRM contact timeline.
labor_costs.updated	colectiva, constanza	[auto-derived] labor_costs.updated event
matter.assigned	agora	An attorney was assigned to a legal matter in Agora — Camino updates CRM contact-to-matter mapping for pipeline visibility
matter.status_changed	agora	A legal matter's status changed in Agora (e.g., open → closed, active → on_hold) — Camino mirrors for CRM pipeline
note.created	agora	Agora attached a note to a matter that should appear in Camino CRM (client communication, case update, billing note).
owner.registered	madriguera	A property or pet owner was registered in Madriguera — Camino creates a CRM contact, Colectiva records the new account for revenue tracking.
product.created	comal	A new product was created in Comal — Camino syncs to the CRM product catalog for cross-channel posting (e.g., TikTok catalog, social feeds).
product.deleted	comal	A Comal product was deleted — Camino removes from cross-channel catalog mirrors.
product.updated	comal	[auto-derived] product.updated event
referral.created	patadas	A business has been referred to an RBS product via the marketplace
site_optimizer.scenario_selected	rito	A Rito user selected a development scenario from the Site Optimizer — Camino records the investment intent for the fund/contact.
subscription.activated	camino, colectiva	A subscription plan has been activated for a tenant — all apps that gate features behind the subscription tier update their local tier state.
subscription.cancelled	camino, colectiva	A subscription has been cancelled — all apps that gate features behind the subscription tier update their local tier state to free/cancelled.
subscription.payment_failed	camino, colectiva	A subscription payment attempt failed — receiver apps surface a payment-failed banner to the tenant operator and may restrict feature access.
subscription.pending_cancellation	camino	A subscription cancellation was scheduled for the end of the current billing period — receiver apps surface a notice that the subscription will end soon.
subscription.renewed	camino, colectiva	A subscription was successfully renewed for a new billing period — receiver apps update the subscription period end date and resume any paused features.
support.ticket_created	(none declared)	A support ticket was opened in any RBS app — Camino mirrors the ticket into support_tickets and runs CATTA Stage 1 classification (Haiku) for cross-app triage. Source app remains the system-of-record for the conversation thread; Camino centralizes triage + escalation + analytics. See docs/architecture/CAMINO_AI_TICKET_SUPPORT.md.
task.completed	servilleta	A gig task has been completed and accepted by the client on Servilleta — triggers payment release from escrow to tasker wallet
upsell.appointment_capacity	plenura	Plenura free-tier therapist has hit or is approaching their monthly booking limit (5/month). Camino surfaces a Plenura Pro upgrade recommendation.
upsell.constanza_onboarding	constanza	Constanza detected an org has no active CSD certificate configured — prompts Camino to surface a CSD setup upsell.
upsell.declaration_service	constanza	Constanza detected an org with overdue declarations (>30 days) — prompts Camino to surface a managed-declarations upsell.
upsell.stamp_upgrade	constanza	Constanza detected an org whose stamp usage has exceeded 80% of its plan allocation — prompts Camino to surface a plan-upgrade upsell.
upsell.task_volume	servilleta	Servilleta free-tier tasker is at or near their active task limit (3 concurrent) or has reached a completed-task volume milestone (10/25/50). Camino surfaces a Pro Tasker upgrade recommendation.
walk.completed	madriguera	[auto-derived] walk.completed event
wallet.deposit_completed	colectiva	A CPI wallet deposit completed in Colectiva — Camino logs activity and sends deposit receipt email to the user.
wallet.withdrawal_completed	colectiva	A CPI wallet SPEI withdrawal completed in Colectiva — Camino logs activity and sends withdrawal receipt email to the user.
workflow.action	colectiva	Colectiva dispatches a workflow action to a target app — instructs the receiver to perform a specific operation (create employee, generate poliza, update record). Payload includes the action type and data needed by the receiver.

Webhook signature

Standard ecosystem HMAC-SHA256 over the raw body, with a 5-minute timestamp window and replay protection. See Webhooks for the verify recipe.

Gotchas

• Every request from a partner app should carry a tenant identifier. Use X-Tenant-Id or resolve server-side via orgResolver — multi-tenant scoping is non-negotiable.
• Refresh tokens are rotating. Always persist the new refresh token returned from /oauth/token.
• The 21 OAuth clients are pre-registered (one per ecosystem app). New third-party integrations require a client registration ticket — they are not self-service today.
• Subscription feature flags are authoritative here. Do not mirror tier state locally without a TTL — check via createSubscriptionClient on the hot path.