Share Secrets API

The Share Secrets API provides a secure mechanism for transmitting sensitive information (such as passwords, private keys, or PII) without leaving a persistent digital footprint. Secrets are encrypted and associated with a unique, short-lived URL. To ensure maximum security, content is purged immediately after the first successful access, rendering the link permanently invalid.

Secret Management

Audit Secret Inventory

Retrieve a paginated directory of all active (unread) or recently expired share secret entries. This allows for administrative tracking of shared links and their current consumption status.

{
  "entities": "ShareSecret",
  "count": 5,
  "per_page": 100,
  "pages": {
    "current": 1,
    "max": 1
  },
  "elements": [
    {
      "id": "6739782b...",
      "name": "Database Migration Credentials",
      "url": "https://hub.donutwork.com/ss/b6a9532aa4a06...",
      "readed": false
    }
  ]
}

Provision Secure Secret Link

Generate a new ephemeral secret link. The content provided is encrypted at rest and will be revealed only once. You can optionally trigger an automated email notification to the recipient.

{
  "shareSecret": {
    "name": "Deployment API Token",
    "content": "secret_value_redacted",
    "sendTo": {
      "email": "engineer@partner-company.com",
      "message": "The requested production API token is now available for one-time retrieval."
    }
  }
}

{
  "id": "67397a4c...",
  "name": "Deployment API Token",
  "url": "https://hub.donutwork.com/ss/fb89f610...",
  "readed": false,
  "readerInfo": {
    "ip": null,
    "ua": null,
    "isoDate": null,
    "ts": null
  },
  "sendTo": {
    "status": true,
    "messageId": "msg_9921"
  }
}

Technical Implementation

const secretPayload = {
  shareSecret: {
    name: "Inter-Service Auth Key",
    content: "PRIVATE_KEY_CONTENT_HERE",
    sendTo: { email: "security-ops@acme.com", message: "Key Rotation: 2026-Q1" }
  }
};

try {
  const response = await sdk.tools.createShareSecret(secretPayload);
  console.log(`Secret Link Generated: ${response.url}`);
} catch (error) {
  console.error(`Provisioning Failed: ${error.message}`);
}

Access & Revocation

Audit Access Metadata

Retrieve the access status and reader telemetry for a specific secret link. This endpoint provides audit trails (IP, User-Agent, Timestamp) once the secret has been consumed.

{
  "id": "6739782b...",
  "name": "Database Migration Credentials",
  "readed": true,
  "readerInfo": {
    "ip": "82.1.4.22",
    "ua": "Mozilla/5.0...",
    "isoDate": "03/03/2026 11:20:00",
    "ts": 1772536800
  }
}

Revoke Secret Link

Manually revoke a secret link before it is consumed, or purge the audit record of an already read secret.

{
  "id": "67397a4c...",
  "deleted": true
}