Organizations

An organization is the top-level tenant entity in Docyard that owns and manages multiple docks, parties, and machine clients. Organizations provide enterprise-grade multi-tenancy, allowing institutional distributors to centralize management while maintaining dock-level isolation.

Why Organizations?

Organizations solve several enterprise challenges:

Centralized Management — Manage multiple document distribution workflows (e.g., different lines of business, subsidiaries, or client portfolios) under a single organizational umbrella
Identity Reuse — The same party (e.g., a title company) can participate as different roles across different docks without creating duplicate recipient records
Machine Authentication — Issue OAuth2-style credentials for automated server-to-server integrations at the organization level
Cross-Dock Analytics — Aggregate audit logs and metrics across all docks within an organization

Organization Hierarchy

Organization (Bank of America)
├── Dock 1: Mortgage Insurance Division
│   ├── Party A: ABC Title Company (role: DISTRIBUTOR)
│   ├── Party B: Wells Fargo (role: RECIPIENT)
│   └── Dock-specific artifacts, policies, recipients
├── Dock 2: Commercial Real Estate Division
│   ├── Party C: CBRE (role: DISTRIBUTOR)
│   ├── Party A: ABC Title Company (role: RECIPIENT) ← Same party, different role!
│   └── Dock-specific artifacts, policies, recipients
├── Party D: JPMorgan Chase (no roles yet)
└── Machine Clients
    ├── boa-mortgage-pusher (scope: artifacts:write, dock: Dock 1)
    └── boa-cre-reader (scope: artifacts:read, dock: Dock 2)

Key Concepts

Organization

The root entity that owns all resources:

Property	Description	Example
Name	Display name for the organization	”Bank of America”
Slug	URL-friendly unique identifier	`bank-of-america`
Metadata	Custom JSON attributes	`{"region": "north-america", "tier": "enterprise"}`

Party

Real-world actors (companies or individuals) within an organization:

Types: INDIVIDUAL or ORGANIZATION
Reuse: One party can have multiple roles across different docks
Identity: Consistent identifiers (tax ID, business registration) across all participation contexts

Example: A title company can be a distributor in Dock 1 (sending policy documents) and a recipient in Dock 2 (reclosing packets).

Dock-Organization Relationship

Ownership: Every dock optionally belongs to an organization
Isolation: Docks remain cryptographically isolated even within the same organization
Cross-Dock Impossibility: Data boundaries are architecturally enforced at the database level

Machine Clients

OAuth2-style credentials issued at the organization level:

Scoped to specific docks or organization-wide
Support granular permissions (artifacts:write, artifacts:read, etc.)
Ideal for automated systems, batch processors, and partner integrations

Real-World Examples

Financial Services: Multi-Division Bank

Organization: MegaBank Corp
Use Case: Different divisions need isolated document distribution with shared counterparties

MegaBank Corp
├── Dock: Mortgage Division
│   ├── Party: First American Title (Distributor)
│   ├── Party: Loan Officer Network (Recipient)
│   └── Machine Client: mortgage-doc-pusher
├── Dock: Wealth Management Division
│   ├── Party: First American Title (Recipient) ← Same title company!
│   ├── Party: High-Net-Worth Clients (Recipients)
│   └── Machine Client: wm-statement-generator
└── Dock: Commercial Banking Division
    ├── Party: CBRE (Distributor)
    └── Party: MegaBank Corp (Recipient) ← Internal distribution

Benefits:

Title company maintains consistent identity across divisions
Separate branding and policies per division
Unified audit trail for compliance

Healthcare: Hospital Network

Organization: Metro Health System
Use Case: Multiple facilities with shared insurers and regulators

Metro Health System
├── Dock: General Hospital
│   ├── Party: Anthem Blue Cross (Recipient)
│   ├── Party: Medical Records Dept (Distributor)
│   └── Machine Client: epic-integration
├── Dock: Children's Hospital
│   ├── Party: Anthem Blue Cross (Recipient) ← Same insurer
│   ├── Party: Pediatric Specialists (Recipients)
│   └── Machine Client: pediatric-portal
└── Dock: Outpatient Clinics
    ├── Party: Anthem Blue Cross (Recipient)
    └── Party: LabCorp (Distributor)

Benefits:

Insurance companies receive documents from multiple facilities under one organization
Compliance officers can audit across all facilities
Patients have consistent identities across the network

Real Estate: Title Company

Organization: Premier Title Services
Use Case: Multiple branch offices with shared lender relationships

Premier Title Services
├── Dock: Downtown Branch
│   ├── Party: Wells Fargo (Recipient)
│   ├── Party: Keller Williams (Distributor)
│   └── Machine Client: downtown-api
├── Dock: Suburban Branch
│   ├── Party: Wells Fargo (Recipient) ← Same lender
│   ├── Party: RE/MAX (Distributor)
│   └── Machine Client: suburban-api
└── Dock: Commercial Division
    ├── Party: CBRE (Distributor)
    ├── Party: Wells Fargo (Recipient)
    └── Party: Insurance Underwriters (Recipient)

Benefits:

Lenders receive consistent document packages from all branches
Branch-level isolation prevents cross-contamination
Centralized management of lender relationships

Lifecycle

Creating an Organization

Organizations are created via API. The slug is auto-generated from the name:

curl -X POST https://api.docyard.io/v1/organizations \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bank of America",
    "metadata": {
      "industry": "financial-services",
      "region": "north-america"
    }
  }'

Response:

{
  "id": "org_01HQ3K...",
  "name": "Bank of America",
  "slug": "bank-of-america",
  "metadata": {
    "industry": "financial-services",
    "region": "north-america"
  },
  "createdAt": "2024-03-01T12:00:00Z",
  "updatedAt": "2024-03-01T12:00:00Z",
  "_count": {
    "docks": 0,
    "parties": 0,
    "machineClients": 0
  }
}

Creating Docks Under an Organization

When creating a dock, specify the organization:

curl -X POST https://api.docyard.io/v1/docks \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mortgage Insurance Division",
    "organizationId": "org_01HQ3K...",
    "domain": "mortgage-docs.bankofamerica.com",
    "legalName": "Bank of America, N.A."
  }'

Backward Compatibility

Existing docks without organizations continue to work normally. You can optionally migrate them to organizations or leave them as standalone docks.

Security & Isolation

Organization-Level Boundaries

Data Access: Resources are queryable only within their organization scope
Machine Clients: Credentials are scoped to the issuing organization
Party Identity: Unique within organization, enabling cross-dock recognition

Cryptographic Isolation

Despite organizational grouping, cryptographic isolation remains absolute:

Foreign key constraints enforce boundaries at the database level
Storage isolation prevents data leakage between docks
Audit logs remain queryable only within dock scope (not automatically cross-dock)

Best Practices

When to Use Organizations

✅ Use Organizations When:

You manage multiple independent document distribution workflows
The same counterparties participate across multiple workflows
You need centralized machine authentication for automated systems
You want unified billing and administration

❌ Don’t Use Organizations When:

You have a single, simple document distribution use case
You need complete separation between business units (use separate accounts)
You’re an individual or small team with one workflow

Design Patterns

One Org Per Enterprise
Create one organization per legal entity, with docks for divisions/lines of business. Dock Per Workflow
Create separate docks for distinct document types or regulatory regimes:

Mortgage insurance vs. commercial insurance
Patient records vs. billing documents
Purchase transactions vs. refinance transactions

Party Per Counterparty
Create one party record per real-world entity, then assign roles in relevant docks.

Parties — Real-world actors with roles in docks
Docks — Isolated workspaces within organizations
Machine Authentication — OAuth2 credentials for automated access

Get Started

Core Concepts

Organizations

Organizations

Why Organizations?

Organization Hierarchy

Key Concepts

Organization

Party

Dock-Organization Relationship

Machine Clients

Real-World Examples

Financial Services: Multi-Division Bank

Healthcare: Hospital Network

Real Estate: Title Company

Lifecycle

Creating an Organization

Creating Docks Under an Organization

Backward Compatibility

Security & Isolation

Organization-Level Boundaries

Cryptographic Isolation

Best Practices

When to Use Organizations

Design Patterns

API Endpoints

Get Started

Core Concepts

​Organizations

​Why Organizations?

​Organization Hierarchy

​Key Concepts

​Organization

​Party

​Dock-Organization Relationship

​Machine Clients

​Real-World Examples

​Financial Services: Multi-Division Bank

​Healthcare: Hospital Network

​Real Estate: Title Company

​Lifecycle

​Creating an Organization

​Creating Docks Under an Organization

​Backward Compatibility

​Security & Isolation

​Organization-Level Boundaries

​Cryptographic Isolation

​Best Practices

​When to Use Organizations

​Design Patterns

​Related Concepts

​API Endpoints

Organizations

Why Organizations?

Organization Hierarchy

Key Concepts

Organization

Party

Dock-Organization Relationship

Machine Clients

Real-World Examples

Financial Services: Multi-Division Bank

Healthcare: Hospital Network

Real Estate: Title Company

Lifecycle

Creating an Organization

Creating Docks Under an Organization

Backward Compatibility

Security & Isolation

Organization-Level Boundaries

Cryptographic Isolation

Best Practices

When to Use Organizations

Design Patterns

Related Concepts

API Endpoints