Central Points

A Central Point is a named mapping from an organization to an orchestrator instance, with a visibility setting (private or public). Clients send X-CENTRAL-ID instead of X-INSTANCE-ID — the server resolves the backing instance and enforces visibility rules. The central point id is stable; the backing orchestrator can be swapped without changing client code.

Why use central points

Without central points, every client integration must track which running instance id currently serves a product feature. Instance ids change when you recreate orchestrators or scale deployments.

A central point is a stable alias (/public-support) that resolves to whatever orchestrator backs it today. Product teams publish one id to mobile apps and partners; operators swap the backing orchestrator in the database without shipping new client builds.

Blue/green deployments: point the central mapping at orchestrator B while A drains, then confirm and complete the cut-over without any client changes.

Creating and targeting a central point

1. Create the orchestrator instance as usual.
2. Create a central point referencing that orchestrator’s id and the desired visibility. private requires a logged-in user with cadence:chat:use for the org. public attaches an anonymous user id for downstream processing (no login required).
3. Clients switch from X-INSTANCE-ID to X-CENTRAL-ID in headers while keeping X-ORG-ID.
4. Monitor for org mismatch or permission denial errors during rollout.

Visibility: private vs. public

cadence/api/tenant/central_point.py

if str(resolved.org_id) != org_id:
    raise HTTPException(
        status_code=status.HTTP_400_BAD_REQUEST,
        detail="Central point does not belong to the specified organization",
    )

if resolved.visibility == "private":
    session = require_session(request)
    oid = str(resolved.org_id)
    if not session.has_permission(CHAT_USE, oid):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Missing permission to use chat for this organization",
        )
    user_id = session.user_id
else:
    user_id = ANONYMOUS_USER_ID

Public endpoints need rate limiting

Public central points can be called without a named user identity. Apply rate limiting and abuse monitoring at your infrastructure layer before exposing them externally.

Response shape

cadence/api/tenant/central_point.py

def _to_response(cp) -> CentralPointResponse:
    return CentralPointResponse(
        id=str(cp.id),
        org_id=str(cp.org_id),
        orchestrator_id=str(cp.orchestrator_id),
        name=cp.name,
        description=cp.description,
        visibility=cp.visibility,
        status=cp.status,
        created_at=cp.created_at.isoformat(),
        updated_at=cp.updated_at.isoformat(),
        is_deleted=getattr(cp, "is_deleted", False),
    )

Troubleshooting

Symptom	Cause	Fix
400 org mismatch	Central point belongs to a different org than the X-ORG-ID header	Verify the org alignment between client and central point
403 on private central point	Caller lacks cadence:chat:use for the org	Check role assignment in that org
Instance errors after swap	New orchestrator not loaded in pool	Load the new instance before updating the central point mapping

Next steps

Real-time streaming Use X-CENTRAL-ID in chat completion requests.

Multi-tenancy How X-ORG-ID and org context interact with central point resolution.