Platform model

DealMeld is organized around tenant workspaces. Every customer record, role, API access key, webhook, billing state, support ticket, and automation policy is scoped to a tenant unless the route is explicitly platform-admin only.

Public integrations should treat tenant context and permissions as part of the request contract, not as optional metadata.

Tenants and workspaces

A tenant is the workspace boundary. CRM, delivery, deal room, signing, billing, support, automation, and audit data belongs to one tenant. Users can belong to more than one tenant, but a request operates in one tenant at a time.

Send tenant context on tenant-scoped requests:

Authorization: Bearer <token>
x-tenant-id: <tenant uuid>

API access keys always require x-tenant-id. User JWT requests can sometimes infer a tenant from membership, but integrations should still send it explicitly so writes are unambiguous.

Users, teams, and invitations

Human users authenticate with the DealMeld sign-in flow and act through their tenant membership. Owners and admins invite people into the tenant, assign roles, disable or remove access, and manage operational settings.

Invitation and membership flows are tenant-scoped:

1. An owner or admin invites a user to a tenant.
2. The invited user accepts the invitation and joins that tenant.
3. The user's tenant role controls what they can read, create, update, delete, export, administer, or configure.
4. Disabling or removing membership should be treated as revoking that user's tenant access, even if the user still exists in another tenant.

Do not use platform-admin routes for customer onboarding. Those routes are for Digital Meld operators.

Roles and permissions

DealMeld combines tenant roles with resource permissions. A valid bearer token does not guarantee access to a route.

Role	Typical use	Boundary
Owner	Workspace owner and final administrator.	Can manage members, settings, API access, billing, and high-risk operations when enabled.
Admin	Operational administrator.	Can manage most workspace operations but may be restricted from owner-only governance actions.
Member	Day-to-day contributor.	Can work assigned CRM, delivery, room, and communication records when granted resource permissions.
Viewer	Read-only or limited-access user.	Should not perform writes, destructive actions, exports, integrations, or billing changes.

Resource permissions apply on top of the role. Examples include companies.read, companies.create, companies.update, deals.update, rooms.read, signing.read, webhooks.create, and audit_logs.read.

Agents and service accounts use scoped API access keys. Their scopes must allow the request method and path, and tenant automation policy can still block mutating requests.

Billing and entitlement boundaries

Billing routes are tenant-scoped but high-risk. Plans, usage limits, checkout, subscription state, refunds, disputes, and entitlement gates should be treated as owner/admin operations unless a route documents a narrower public flow.

Integrations should not infer billing permissions from ordinary CRM access. If a request returns 403, a feature-disabled response, or an entitlement error, ask an owner/admin to update the tenant plan, role, or feature configuration instead of retrying as a transient failure.

Support flows

Support records are tenant-scoped. When opening a support request or linking an API failure to a support ticket, include:

• Tenant ID
• Request method and path
• Timestamp with timezone
• Response status and error.code
• Any request or trace ID returned by the API

Never include raw API keys, JWTs, signing URLs, private customer records, or provider secrets in support messages.

Public, internal, and admin-only surfaces

DealMeld exposes three broad API classes:

Surface	Who should use it	Examples
Public tenant API	Customer users, service accounts, agents, and external integrations.	CRM, contacts, deals, rooms, communications, imports, jobs, webhooks, API access, and documented signing flows.
Capability discovery and runtime	Agents and connector importers.	/api/agent/capabilities, /api/agent/openapi.json, /api/agent/mcp.json, authenticated /api/agent/mcp, /api/agent/a2a-card.json, connector artifacts, and templates.
Platform admin	Digital Meld operators only.	/api/admin tenant, user, billing, support, ops, and system management routes.

If a route is absent from the interactive API reference, use the Complete API surface to identify whether it is a tenant route, a discovery artifact, or platform-admin only. Do not assume an undocumented route is supported for external automation.

Onboarding checklist

For a customer or integration onboarding flow:

1. Create or select the tenant workspace.
2. Invite owners/admins before ordinary members.
3. Assign the smallest role and permission set needed.
4. Create API access keys only for server-side automations.
5. Store API keys in a server-side secret manager.
6. Send x-tenant-id on every tenant-scoped integration request.
7. Verify feature gates, entitlement state, and module access before writes.
8. Use audit logs and support tickets for investigation instead of exposing private data in external messages.

Agent checklist

Before an agent mutates tenant data:

1. Discover capabilities and required scopes.
2. Confirm tenant context.
3. Check the route is tenant-callable, not platform-admin only.
4. Use the narrowest supported endpoint for the task.
5. Include idempotency keys on retried writes where supported.
6. Convert risky external sends, destructive updates, billing changes, and signing actions into approval requests when policy requires it.