Cloud Connector for Azure API Reference

API Reference

Overview

Cloud Connector for Azure provides businesses with a scalable, cost-effective API in their own infrastructure to seal even the most sensitive documents. By deploying the connector in their own Azure subscription, customers have assurance that none of the information in the documents can be intercepted or modified.

The Azure connector is deployed as an Azure Function. Customers send a PDF to sign with an API key and some parameters, and the function returns a sealed PDF.

Direct Mode and Storage Mode

Cloud Connector for Azure provides two modes of operation:

Direct Mode: Send PDF content directly in the request (up to 50MB)
Storage Mode: Process large files via Azure Blob Storage (unlimited size)

Architecture Overview

Process Flow - Direct Mode

Process Flow - Storage Mode

Authentication

All requests require valid Trusted Signatures API credentials:

API Key: Hex-encoded string from https://secure.trusted-signatures.com
API Key ID: Your unique key identifier

Endpoints

POST /api/seal-pdf

Seals a PDF document with a digital signature.

Direct Mode Request

1
2
3
4
5
6
7
8
9
{
  "pdf": "JVBERi0xLjQK...",
  "apiKey": "aabbccdd0011223344",
  "apiKeyId": "my-key-id",
  "endpoint": "https://api.trusted-signatures.com",
  "tsaTimestamp": true,
  "includeLtv": false,
  "limitChanges": "allow-forms"
}

Storage Mode Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "sourceContainer": "input-pdfs",
  "sourceBlob": "document.pdf",
  "destinationContainer": "sealed-pdfs",
  "destinationBlob": "document-sealed.pdf",
  "apiKey": "aabbccdd0011223344",
  "apiKeyId": "my-key-id",
  "endpoint": "https://api.trusted-signatures.com",
  "tsaTimestamp": true,
  "includeLtv": false,
  "limitChanges": "allow-forms"
}

Parameters

Parameter	Type	Required	Description
`pdf`	string	Conditional	Base64-encoded PDF (required for direct mode)
`sourceContainer`	string	Conditional	Azure Blob container name (required for storage mode)
`sourceBlob`	string	Conditional	Azure Blob name (required for storage mode)
`destinationContainer`	string	Optional	Output container (defaults to sourceContainer)
`destinationBlob`	string	Optional	Output blob name (defaults to “sealed-{sourceBlob}”)
`apiKey`	string	Yes	Hex-encoded API key
`apiKeyId`	string	Yes	API key identifier
`endpoint`	string	No	API endpoint (default: https://api.trusted-signatures.com)
`tsaTimestamp`	boolean	No	Include timestamp (default: false)
`includeLtv`	boolean	No	Include long-term validation data (default: false)
`limitChanges`	string	No	Document modification permissions

limitChanges Values

no-changes: No modifications allowed
allow-forms: Allow form filling only
allow-comments: Allow form filling and annotations

Direct Mode Response

Success (200):

1
2
Content-Type: application/pdf
<binary PDF data>

Storage Mode Response

Success (200):

1
2
3
4
5
6
7
8
{
  "message": "PDF sealed and uploaded successfully",
  "container": "sealed-pdfs",
  "blob": "document-sealed.pdf",
  "ltv": {
    /* LTV data if requested */
  }
}

Error Response

Error (400/500):

1
2
3
{
  "error": "Human readable error message"
}

GET /api/health

Health check endpoint for monitoring.

Response (200):

1
2
3
4
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Size Limits

Direct Mode: 50MB maximum PDF size
Storage Mode: No size limit (limited by Azure Blob Storage)

Error Codes

Status	Description
200	Success
400	Bad Request (validation error, invalid PDF, etc.)
401	Unauthorized (invalid API key)
413	Payload Too Large (>50MB in direct mode)
500	Internal Server Error

Rate Limits

Rate limits are enforced by the Trusted Signatures API service. Contact support for current limits.

Code Examples

Python - Direct Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import requests
import base64

# Read and encode PDF
with open('document.pdf', 'rb') as f:
    pdf_base64 = base64.b64encode(f.read()).decode('utf-8')

# Seal PDF directly
response = requests.post(
    'https://your-gateway.azurewebsites.net/api/seal-pdf',
    json={
        'pdf': pdf_base64,
        'apiKey': 'your-hex-api-key',
        'apiKeyId': 'your-key-id',
        'tsaTimestamp': True,
        'limitChanges': 'allow-forms'
    }
)

# Save sealed PDF
with open('sealed-document.pdf', 'wb') as f:
    f.write(response.content)

Python - Storage Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import requests
from azure.storage.blob import BlobServiceClient

# Upload PDF to Azure Blob Storage first
blob_service = BlobServiceClient.from_connection_string('your-connection-string')
with open('large-document.pdf', 'rb') as f:
    blob_service.get_blob_client(
        container='input-pdfs',
        blob='large-document.pdf'
    ).upload_blob(f, overwrite=True)

# Seal PDF via storage
response = requests.post(
    'https://your-gateway.azurewebsites.net/api/seal-pdf',
    json={
        'sourceContainer': 'input-pdfs',
        'sourceBlob': 'large-document.pdf',
        'destinationContainer': 'sealed-pdfs',
        'destinationBlob': 'large-document-sealed.pdf',
        'apiKey': 'your-hex-api-key',
        'apiKeyId': 'your-key-id',
        'tsaTimestamp': True
    }
)

result = response.json()
print(f"Sealed PDF saved to: {result['container']}/{result['blob']}")

TypeScript - Direct Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import * as fs from "fs";

interface SealRequest {
  pdf?: string;
  sourceContainer?: string;
  sourceBlob?: string;
  destinationContainer?: string;
  destinationBlob?: string;
  apiKey: string;
  apiKeyId: string;
  tsaTimestamp?: boolean;
  limitChanges?: "no-changes" | "allow-forms" | "allow-comments";
}

// Direct mode - seal PDF from file
async function sealPdfDirect(filePath: string): Promise<Buffer> {
  const pdfBuffer = fs.readFileSync(filePath);
  const pdfBase64 = pdfBuffer.toString("base64");

  const request: SealRequest = {
    pdf: pdfBase64,
    apiKey: process.env.TS_API_KEY!,
    apiKeyId: process.env.TS_API_KEY_ID!,
    tsaTimestamp: true,
    limitChanges: "allow-forms",
  };

  const response = await fetch(
    "https://your-gateway.azurewebsites.net/api/seal-pdf",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(request),
    }
  );

  return Buffer.from(await response.arrayBuffer());
}

// Usage
sealPdfDirect("./contract.pdf").then((sealedPdf) =>
  fs.writeFileSync("./sealed-contract.pdf", sealedPdf)
);

TypeScript - Storage Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import { BlobServiceClient } from "@azure/storage-blob";

// Storage mode - seal large PDF via Azure Blob
async function sealPdfStorage(
  sourceContainer: string,
  sourceBlob: string,
  destinationContainer?: string
): Promise<{ container: string; blob: string }> {
  const request: SealRequest = {
    sourceContainer,
    sourceBlob,
    destinationContainer: destinationContainer || sourceContainer,
    destinationBlob: `sealed-${sourceBlob}`,
    apiKey: process.env.TS_API_KEY!,
    apiKeyId: process.env.TS_API_KEY_ID!,
    tsaTimestamp: true,
  };

  const response = await fetch(
    "https://your-gateway.azurewebsites.net/api/seal-pdf",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(request),
    }
  );

  const result = await response.json();
  return { container: result.container, blob: result.blob };
}

// Usage
sealPdfStorage("input-pdfs", "large-contract.pdf", "sealed-pdfs").then(
  (result) => console.log(`Sealed PDF: ${result.container}/${result.blob}`)
);

Bash - Direct Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#!/bin/bash

# Seal PDF directly
API_KEY="your-hex-api-key"
API_KEY_ID="your-key-id"
GATEWAY_URL="https://your-gateway.azurewebsites.net/api/seal-pdf"

# Encode PDF to base64
PDF_BASE64=$(base64 -i document.pdf)

# Create request payload
cat > request.json << EOF
{
  "pdf": "$PDF_BASE64",
  "apiKey": "$API_KEY",
  "apiKeyId": "$API_KEY_ID",
  "tsaTimestamp": true,
  "limitChanges": "allow-forms"
}
EOF

# Send request and save sealed PDF
curl -X POST "$GATEWAY_URL" \
  -H "Content-Type: application/json" \
  -d @request.json \
  --output sealed-document.pdf

echo "Sealed PDF saved as sealed-document.pdf"
rm request.json

Bash - Storage Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
#!/bin/bash

# Seal PDF via Azure Blob Storage
API_KEY="your-hex-api-key"
API_KEY_ID="your-key-id"
GATEWAY_URL="https://your-gateway.azurewebsites.net/api/seal-pdf"

# Upload PDF to blob storage first (using Azure CLI)
az storage blob upload \
  --account-name "yourstorageaccount" \
  --container-name "input-pdfs" \
  --name "large-document.pdf" \
  --file "./large-document.pdf"

# Seal PDF via storage
curl -X POST "$GATEWAY_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceContainer": "input-pdfs",
    "sourceBlob": "large-document.pdf",
    "destinationContainer": "sealed-pdfs",
    "destinationBlob": "large-document-sealed.pdf",
    "apiKey": "'$API_KEY'",
    "apiKeyId": "'$API_KEY_ID'",
    "tsaTimestamp": true
  }' | jq .

echo "Check sealed-pdfs container for sealed PDF"

PowerShell - Direct Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Seal PDF directly
$apiKey = "your-hex-api-key"
$apiKeyId = "your-key-id"
$gatewayUrl = "https://your-gateway.azurewebsites.net/api/seal-pdf"

# Read and encode PDF
$pdfBytes = [System.IO.File]::ReadAllBytes("document.pdf")
$pdfBase64 = [System.Convert]::ToBase64String($pdfBytes)

# Create request
$body = @{
    pdf = $pdfBase64
    apiKey = $apiKey
    apiKeyId = $apiKeyId
    tsaTimestamp = $true
    limitChanges = "allow-forms"
} | ConvertTo-Json

# Send request
$response = Invoke-RestMethod -Uri $gatewayUrl -Method POST `
    -ContentType "application/json" -Body $body

# Save sealed PDF
[System.IO.File]::WriteAllBytes("sealed-document.pdf", $response)
Write-Host "Sealed PDF saved as sealed-document.pdf"

PowerShell - Storage Mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Seal PDF via Azure Blob Storage
$apiKey = "your-hex-api-key"
$apiKeyId = "your-key-id"
$gatewayUrl = "https://your-gateway.azurewebsites.net/api/seal-pdf"

# Upload PDF to blob storage first
$storageContext = New-AzStorageContext -StorageAccountName "yourstorageaccount" -StorageAccountKey "your-key"
Set-AzStorageBlobContent -File "large-document.pdf" `
    -Container "input-pdfs" -Blob "large-document.pdf" -Context $storageContext

# Seal PDF via storage
$body = @{
    sourceContainer = "input-pdfs"
    sourceBlob = "large-document.pdf"
    destinationContainer = "sealed-pdfs"
    destinationBlob = "large-document-sealed.pdf"
    apiKey = $apiKey
    apiKeyId = $apiKeyId
    tsaTimestamp = $true
} | ConvertTo-Json

$result = Invoke-RestMethod -Uri $gatewayUrl -Method POST `
    -ContentType "application/json" -Body $body

Write-Host "Sealed PDF saved to: $($result.container)/$($result.blob)"

Security Considerations

Store API keys in Azure Key Vault, not in code
Use managed identities for Azure resource access
Rotate API keys annually (maximum lifetime: 1 year)
Restrict network access using Azure networking features
Monitor API usage through Application Insights
Use HTTPS only (enforced by default)