Shared Access

These routes are public (no Clerk session) — access is granted by the policy itself. Every successful access increments the policy's accessCount and is written to the access log. These routes live at the server root (no /api prefix), except the access log.

A successful response always has this shape:

{
  "documentId": "abc123xyz",
  "fileName": "contrato.pdf",
  "serialNumber": "JAT-7K2M9",
  "accessUrl": "https://...presigned...",
  "permission": "download",
  "expiresInSeconds": 3600
}

accessUrl is presigned for 1 hour (download) or 15 minutes (view).

GET /share/:token

Access via a share-link token (created by a link policy).

404 invalid token · 410 expired or max accesses reached.

GET /access/public/:documentId

Access a document that has an active public policy.

404 not publicly shared · 410 public access expired.

POST /access/wallet/:documentId

Prove wallet ownership by signing a message. The signature is cryptographically verified, and the signed message must contain the documentId — this prevents replaying a signature captured for one document against another.

Body field	Type	Description
`address`	string (required)	Wallet address (`0x...`)
`signature`	string (required)	Signature over `message`
`message`	string (required)	The original signed message, must include the document ID

400 invalid address · 401 invalid signature, message without document ID, or wallet not authorized.

POST /access/email/:documentId/request

Request access by email. The response is identical whether or not the email is authorized, so the endpoint can't enumerate recipients:

{ "message": "If user@example.com is authorized, an access link has been sent." }

In development a token field is included for testing. Email delivery is not yet wired in production.

GET /access/email/verify/:token

Magic-link verification. Currently returns 501 Not Implemented — use share links instead.

GET /access-log/:documentId

Auth required (owner only). Returns the access trail for a document:

{
  "log": [
    {
      "id": "log123",
      "accessorType": "wallet",
      "accessorIdentifier": "0xabc...",
      "permission": "download",
      "ip": "203.0.113.7",
      "createdAt": "2026-05-02T09:00:00.000Z"
    }
  ]
}

accessorType is anonymous (link/public) or wallet.