Actors & Permissions

Every API key is scoped to an organisation and an actor type, determining what actions are available and what data is visible.

The Curvestone platform uses a multi-tenant model. Organisations sit in a hierarchy (Enterprise → Network → Brokerage → Broker) and every API key carries an actor type that controls both capabilities (what you can do) and scope (what data you can see). This means a broker key can only submit and query their own cases, while a network key can review and monitor across all child brokerages.

Actor Types

Actor	Capabilities	Scope	Interface
Broker / Adviser	submitask	Own cases	CRM integration, API
Compliance Officer	reviewaskmonitor	Team	Dashboard, API
Network / Principal	reviewconfiguremonitor	All brokerages	Admin dashboard, API
Lender	configuremonitor	Own	Lender portal, API
CRM Partner	submitmonitor	Team (via X-Actor)	Direct API

Capabilities

submit

Create jobs by uploading documents and specifying case type, depth, and modifiers.

review

Review flagged jobs. View findings, remedial actions, and full audit trails.

configure

Set policies, thresholds, custom skills, and templates for an organisation.

ask

Query completed jobs or documents conversationally. Get plain-language answers with source citations.

monitor

Set up recurring watches on external URLs, lender criteria, or internal quality metrics.

Scopes

own

Only see your own submissions and their results. Typical for individual brokers and lenders.

team

See all submissions within your brokerage or organisation. Used by compliance officers and CRM partners.

all

See all submissions across every child organisation in the hierarchy. Reserved for networks and principals.

CRM Integration

Platform partners submit jobs on behalf of individual users using the X-Actor header. The CRM authenticates with its own API key, and the header tells Curvestone which broker the submission belongs to. This means the broker sees the result in their own dashboard, scoped to their own cases.

crm_integration.py

python

from curvestone import Agent

agent = Agent(
    api_key="cs_live_xxxxxxxxxxxx",
    default_headers={"X-Actor": "broker_12345"},
)

# Submits job on behalf of broker_12345
result = agent.check(
    case_type="residential_mortgage",
    depth="full_check",
    documents=[open("fact_find.pdf", "rb")],
)

Organisation Hierarchy

Organisations are structured as Enterprise → Network → Brokerage → Broker. Billing rolls up from the bottom: each broker's usage is aggregated at the brokerage level, then at the network level. Compliance policies inherit from the parent organisation and can be overridden at any level below. For example, a network can set a minimum check depth of "full_check" that applies to all its child brokerages, while an individual brokerage can add additional modifiers on top.