Generate a Secret
Generates a new shared passphrase for a recipient. This is the primary authentication factor for mortgagee recipients who access artifacts via the bulk retrieval API. The passphrase is combined with a mutual TLS certificate to complete the two-factor authentication required by mortgagee access policies.
POST /v1/recipients/:recipientId/secrets
Path Parameters
| Parameter | Type | Description |
|---|
recipientId | string | The recipient ID |
Request Body
| Parameter | Type | Required | Description |
|---|
name | string | Required | A label for this secret (e.g., the mortgagee’s name + purpose) |
expiresInDays | integer | Optional | Number of days until the secret expires. Omit for no expiry. Recommended: 90 days for mortgagees. |
Example: Mortgagee Passphrase
Generate a shared passphrase for a mortgage lender’s bulk API access:
curl -X POST https://api.docyard.io/v1/recipients/rcp_01HQ3N.../secrets \
-H "Authorization: Bearer dk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{
"name": "First National Bank — Bulk API Passphrase",
"expiresInDays": 90
}'
Response
{
"id": "sec_01HQ3T...",
"secret": "dk_sec_7f2a9b4c1e8d3f6a0b5c2d9e4f7a1b8c",
"name": "First National Bank — Bulk API Passphrase",
"expiresAt": "2025-04-15T10:32:00.000Z"
}
Error Handling
| Status | Condition |
|---|
400 | name is missing |
401 | Missing or invalid API key |
404 | Recipient not found |
The secret value is returned only once in this response. Docyard stores only the SHA-256 hash and cannot recover the plaintext. Transmit it to the mortgagee through a secure channel (encrypted email, secure portal). If lost, you must rotate the secret to generate a new one. Typical Workflow
- Create a mortgagee recipient with
lender_id and policy_number identifiers
- Generate a passphrase (this endpoint) with a 90-day expiration
- Securely transmit the passphrase to the mortgagee
- The mortgagee configures their mutual TLS certificate
- Create a mortgagee policy requiring
shared_passphrase + tls_certificate factors
- Publish the policy to production
- The mortgagee authenticates with passphrase + mTLS to create bulk retrieval jobs
Passphrases are only used by mortgagee recipients. Agents use WebAuthn, policyholders use SMS OTP, and auditors use badge ID + NDA hash — none of these personas require a generated secret.
