List Machine Clients
Retrieves a list of all machine clients within an organization. For security, secrets are never returned in list responses.
GET /v1/organizations/:orgId/machine-clients
Path Parameters
| Parameter | Type | Required | Description |
|---|
orgId | string | Required | Organization ID (prefix: org_) |
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 20 | Maximum items to return (max 100) |
offset | integer | 0 | Number of items to skip |
dockId | string | - | Filter by dock |
isActive | boolean | - | Filter by active status |
Example Request
# List all machine clients
curl https://api.docyard.io/v1/organizations/org_01HQ3K.../machine-clients \
-H "Authorization: Bearer dk_live_a1b2c3d4..."
# Filter by dock
curl "https://api.docyard.io/v1/organizations/org_01HQ3K.../machine-clients?dockId=dock_metro_general" \
-H "Authorization: Bearer dk_live_a1b2c3d4..."
# Show only active clients
curl "https://api.docyard.io/v1/organizations/org_01HQ3K.../machine-clients?isActive=true" \
-H "Authorization: Bearer dk_live_a1b2c3d4..."
Response
{
"data": [
{
"id": "mc_01HQ3K9B2...",
"clientId": "dyc_epic_prod_a1b2c3d4",
"name": "epic-ehr-integration",
"scopes": ["artifacts:write", "artifacts:read"],
"dockId": "dock_metro_general",
"organizationId": "org_01HQ3K...",
"partyId": "pty_metro_health",
"isActive": true,
"createdAt": "2024-03-01T12:00:00.000Z"
},
{
"id": "mc_01HQ3L9C3...",
"clientId": "dyc_github_actions_xyz789",
"name": "github-actions-pipeline",
"scopes": ["artifacts:write"],
"dockId": "dock_build_artifacts",
"organizationId": "org_01HQ3K...",
"partyId": null,
"isActive": true,
"createdAt": "2024-02-15T09:30:00.000Z"
}
],
"meta": {
"total": 5,
"page": 1,
"pageSize": 20,
"hasMore": false
}
}
Response Fields
| Field | Type | Description |
|---|
data | array | List of machine clients |
data[].id | string | Client identifier (prefix: mc_) |
data[].clientId | string | OAuth2 client ID (prefix: dyc_) |
data[].name | string | Human-readable identifier |
data[].scopes | array | Granted permission scopes |
data[].dockId | string | Restricted dock (null if org-wide) |
data[].organizationId | string | Parent organization |
data[].partyId | string | Linked party for audit trails |
data[].isActive | boolean | Activation status |
data[].createdAt | string | ISO 8601 timestamp |
meta.total | integer | Total machine clients |
meta.hasMore | boolean | Whether more results exist |
Security Note: Client secrets (dys_...) are never returned in list or get responses. They are shown only once during creation. If a secret is lost, you must rotate it.
Error Handling
| Status | Condition |
|---|
401 | Missing or invalid API key |
404 | Organization not found |
Use Cases
Security Audit: Review all automated integrations and their permission scopes.
Compliance Review: Identify which systems have access to which docks.
Client Management: Deactivate unused clients by setting isActive: false.
Managing Client Access
To revoke a machine client’s access:
- Update
isActive to false (soft delete)
- Or rotate the secret to invalidate existing tokens
# Deactivate a client
curl -X PATCH https://api.docyard.io/v1/organizations/{orgId}/machine-clients/{clientId} \
-H "Authorization: Bearer dk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{"isActive": false}'
