Create Machine Client

Creates a machine client — OAuth2 client credentials for server-to-server (S2S) integrations. The client secret is returned only once and must be stored securely.

POST /v1/organizations/:orgId/machine-clients

Path Parameters

Parameter	Type	Required	Description
`orgId`	string	Required	Organization ID (prefix: `org_`)

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Human-readable identifier (e.g., `epic-ehr-integration`)
`dockId`	string	Optional	Restrict client to specific dock (recommended)
`scopes`	array	Optional	Permission scopes (defaults to all available)
`partyId`	string	Optional	Link to party record for audit trails

Available Scopes

Scope	Description	Use Case
`artifacts:write`	Create/upload artifacts	EHR integration pushing medical records
`artifacts:read`	List and retrieve artifacts	Partner system downloading documents
`policies:read`	Read access policies	Compliance system auditing rules
`recipients:read`	Read recipient catalog	CRM integration syncing contacts
`audit:read`	Read audit logs	SIEM integration for security monitoring

Example Request

Healthcare EHR
Financial Services
CI/CD Pipeline

curl -X POST https://api.docyard.io/v1/organizations/org_01HQ3K.../machine-clients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "epic-ehr-integration",
    "dockId": "dock_metro_general",
    "scopes": ["artifacts:write", "artifacts:read"],
    "partyId": "pty_metro_health_system"
  }'

curl -X POST https://api.docyard.io/v1/organizations/org_01HQ3K.../machine-clients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mortgage-doc-pusher",
    "dockId": "dock_mortgage_ops",
    "scopes": ["artifacts:write"],
    "partyId": "pty_wells_fargo"
  }'

curl -X POST https://api.docyard.io/v1/organizations/org_01HQ3K.../machine-clients \
  -H "Authorization: Bearer dk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-actions-pipeline",
    "dockId": "dock_build_artifacts",
    "scopes": ["artifacts:write"]
  }'

Response

CRITICAL: The clientSecret is displayed only once upon creation. Store it immediately in a secrets manager. If lost, you must rotate the secret.

{
  "id": "mc_01HQ3K9B2...",
  "clientId": "dyc_epic_prod_a1b2c3d4",
  "clientSecret": "dys_live_efghijklmnop...",
  "name": "epic-ehr-integration",
  "scopes": ["artifacts:write", "artifacts:read"],
  "dockId": "dock_metro_general",
  "organizationId": "org_01HQ3K...",
  "partyId": "pty_metro_health_system",
  "isActive": true,
  "createdAt": "2024-03-01T12:00:00.000Z"
}

Response Fields

Field	Type	Description
`id`	string	Machine client identifier (prefix: `mc_`)
`clientId`	string	OAuth2 client identifier (prefix: `dyc_`)
`clientSecret`	string	OAuth2 client secret (prefix: `dys_`) — shown only once
`name`	string	Human-readable identifier
`scopes`	array	Granted permission scopes
`dockId`	string	Restricted dock (null if organization-wide)
`organizationId`	string	Parent organization
`partyId`	string	Linked party for audit trails
`isActive`	boolean	Whether client is active
`createdAt`	string	ISO 8601 timestamp

Token Prefix Reference

Prefix	Type	Example
`dyc_`	Machine Client ID	`dyc_epic_prod_a1b2c3d4`
`dys_`	Machine Client Secret	`dys_live_efghijklmnop...`
`dyt_`	Machine Access Token	`dyt_live_qrstuvwx...`

Security Best Practices

Dock Scoping: Always specify dockId unless the client needs organization-wide access. This limits the blast radius if credentials are compromised. Scope Selection: Request only the scopes you need:

Ingestion-only: ["artifacts:write"]
Retrieval-only: ["artifacts:read"]
Full access: ["artifacts:write", "artifacts:read"]

Secret Storage: Store in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault), never in source code or environment variables in plain text.

Error Handling

Status	Condition
`400`	Invalid scopes or missing required fields
`401`	Missing or invalid API key
`404`	Organization, dock, or party not found

Next Steps

After creating a machine client:

Store the secret securely in a secrets manager
Issue an access token via OAuth2 token endpoint
Make API calls using the bearer token
Implement token refresh logic in your application

Machine Authentication Setup — Step-by-step guide
Token Endpoint — OAuth2 token issuance
Machine Artifacts API — Upload artifacts via machine auth

API Reference

Organizations

Parties

Machine Authentication

Docks

Artifacts

Recipients

Recipient Groups

Policies

Retrieval

Secrets

Audit

Notifications

Identity

Create Machine Client