Skip to main content

​
Get Policy

Retrieve policy information and associated IPFS CID for accessing content.

​
Endpoint

GET /api/getPolicy/{policyId}
Authorization: Bearer {token}

​
Parameters

ParameterTypeRequiredDescription
policyIdstring✅Policy identifier (path param)

​
Response

​
Success (200)

{
  "success": true,
  "policy": {
    "policyId": "0xabc123...",
    "cid": "QmXyz...",
    "sender": "0x742d...",
    "recipient": "0x1234...",
    "expiry": 1708608000,
    "maxAttempts": 3,
    "attempts": 1,
    "contentType": "file",
    "fileName": "document.pdf",
    "fileSize": 1048576,
    "valid": true,
    "createdAt": "2025-02-22T10:00:00Z"
  }
}

​
Policy Expired (410)

{
  "error": "Policy expired",
  "expiry": 1708608000
}

​
Policy Not Found (404)

{
  "error": "Policy not found"
}

​
Unauthorized (401)

{
  "error": "Unauthorized"
}

​
Max Attempts Reached (403)

{
  "error": "Max attempts reached",
  "attempts": 3,
  "maxAttempts": 3
}

​
Example Usage

​
JavaScript

async function getPolicy(policyId: string) {
  const response = await fetch(`/api/getPolicy/${policyId}`, {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return await response.json();
}

// Usage
const { policy } = await getPolicy('0xabc123...');
console.log(`CID: ${policy.cid}`);
console.log(`Expires: ${new Date(policy.expiry * 1000)}`);

​
cURL

curl https://app.shieldhq.xyz/api/getPolicy/0xabc123... \
  -H "Authorization: Bearer $TOKEN"

​
Policy Status Checks

The endpoint performs multiple validations:
CheckHTTP StatusResponse
Policy exists200Full policy data
Policy not found404{ error: "Policy not found" }
Expired410{ error: "Policy expired" }
Revoked403{ error: "Policy revoked" }
Max attempts403{ error: "Max attempts reached" }

​
Access Flow Integration

async function accessContent(policyId: string, secretKey: string) {
  // 1. Get policy metadata
  const { policy } = await getPolicy(policyId);

  // 2. Authenticate with SIWE (recipient)
  const token = await authenticate(recipientAddress);

  // 3. Log access on-chain
  await logAccessAttempt(policyId);

  // 4. Fetch encrypted content from IPFS
  const encrypted = await fetchFromIPFS(policy.cid);

  // 5. Decrypt with secret key
  const decrypted = await decryptContent(encrypted, secretKey);

  return decrypted;
}

​
Response Fields

FieldTypeDescription
policyIdstringPolicy identifier
cidstringIPFS Content Identifier
senderaddressCreator’s wallet address
recipientaddressAuthorized recipient address
expirynumberUnix timestamp
maxAttemptsnumberMaximum allowed attempts
attemptsnumberCurrent attempt count
contentTypestring"file" or "message"
fileNamestringOriginal filename
fileSizenumberSize in bytes
validbooleanWhether policy is still valid
createdAtstringISO timestamp of creation

​
Rate Limits

LimitValue
Requests60 per minute
Per policyNo limit

​
Caching

Policies are cached for 30 seconds to reduce database load. The cache is invalidated on:
  • Policy revocation
  • Access attempt logged

​
Error Handling

try {
  const { policy } = await getPolicy(policyId);
} catch (error) {
  switch (error.message) {
    case 'Policy not found':
      // Invalid policy ID
      break;
    case 'Policy expired':
      // Link has expired
      break;
    case 'Max attempts reached':
      // No more access allowed
      break;
    case 'Policy revoked':
      // Sender revoked access
      break;
    default:
      // Network or server error
  }
}