Sharing & signatures
A share and a signature envelope are records in the organisation. Creating them is an API call. Opening them is a separate door: Secure Share (OTP), optional Direct Download when the organisation allows it, watermark policy, a signing ceremony. Your client secret never becomes their session.
Call these from an API user with shares or organisation (and signatures for envelopes). Recipients never present this token. If they did, they would be you.
GET /v1/organisations/share-policy · PUT /v1/organisations/share-policy
Secure Share download defaults and ceilings; optional Direct Download (allow_direct_download_share, Direct ceilings up to 20); require_watermark_on_external_share (default true). If you omit max_downloads on create, Casewelt uses the matching Secure or Direct default. Codes: share_policy_invalid, max_downloads_exceeds_org_policy, share_policy_direct_max_exceeds_platform.
/v1/shares
Secure Share is the default (otp_required omitted or true): the response includes a public URL and a one-time code (not emailed with the link by default). Direct Download sets otp_required: false only when policy allows it: no OTP in the response, tighter TTL (7 days). Watermark follows org policy. List with GET /v1/shares?file_id=. Refuse codes include direct_download_share_disabled and watermark_required_for_external_share.
{
"workspace_id": "…",
"file_id": "…",
"version_id": "…",
"notify_email": "jordan@example.com",
"otp_required": true,
"watermark_required": true,
"ttl_amount": 14,
"ttl_unit": "day",
"max_downloads": 1,
"note": "Board pack: version you approved.",
"include_otp_in_email": false,
"scheduled_send_at": null
}{
"share_id": "…",
"public_url": "https://share.casewelt.com/…",
"otp": "482913",
"otp_required": true,
"watermark_required": true,
"otp_delivered": false,
"send_status": "sent",
"expires_at": "2026-09-20T00:00:00Z"
}/v1/shares
Send two to fifty file versions under one public token, one recipient check and one expiry. The recipient gets a gateway list with per-item downloads and, when enabled, an optional ZIP. This is a fixed package, not access to a folder.
{
"workspace_id": "…",
"items": [
{ "file_id": "…", "version_id": "…" },
{ "file_id": "…", "version_id": "…" }
],
"notify_email": "jordan@example.com",
"otp_required": true,
"ttl_amount": 14,
"ttl_unit": "day",
"max_downloads": 1
}one public URL
one OTP and expiry
per-item download counts
optional gateway ZIP/v1/shares/{id}/revoke
Ends the share and any viewer sessions already open. A later open is refused and recorded. You do not rotate staff passwords to achieve this.
{ "status": "share_revoked", "share_id": "…", "viewer_sessions_revoked": 2 }GET /v1/internal-shares · POST /v1/internal-shares
A colleague or a group, still inside the organisation. No public door, no watermark for staff. Authorisation is still checked. List colleagues for a workspace with GET /v1/internal-shares/colleagues?workspace_id=.
/v1/signature-envelopes
{
"workspace_id": "…",
"file_id": "…",
"version_id": "…",
"signers": [
{ "email": "counsel@example.com", "name": "Jordan A." }
]
}List with GET /v1/signature-envelopes. Read one for status, certificate, final document and evidence. Standard versus qualified is an entitlement on the organisation, not a flag you invent. When the allowance is used up, create fails with a usage error rather than sending a half-ceremony.
| Code | Meaning |
|---|---|
policy_denied | This file must not leave. The caller is still authenticated. |
otp_required_for_external_share | The product will not emit an unmarked public copy. |
watermark_required_for_external_share | Same: public copy must be marked. |
external_share_disabled | Organisation policy has closed that door. |
deny | This principal may not share this file. |