Usage

Security: To verify the container’s authenticity and inspect its SBOM, see the Attestation & Verification Guide.

Using the Container

Run the API proxy container with Docker:

docker run -p 8080:8080 subnoto/api-proxy:latest

The container exposes the API proxy service on port 8080. You can map this to any port on your host machine by changing the first port number (e.g., -p 3000:8080 to expose on port 3000).

Mac users (Apple Silicon): If you encounter connection issues, explicitly bind to localhost and specify the platform:

docker run --platform linux/amd64 -p 127.0.0.1:8080:8080 subnoto/api-proxy:latest

Note: The container does not require environment variables to run. API credentials are provided when making requests, not when starting the container.

API Authentication

To use the API proxy, you need an access key and secret key. These credentials are provided when you create an API key in your Subnoto workspace.

Obtaining Credentials

1. Log into your Subnoto workspace at app.subnoto.com
2. Navigate to Settings → API Keys
3. Create a new API key
4. Save the ACCESS_KEY and SECRET_KEY securely

Making Authenticated Requests

Include your credentials in the Authorization header using the Bearer token format:

Authorization: Bearer $ACCESS_KEY:$SECRET_KEY

Basic API Usage

Test your connection with the whoami endpoint:

curl http://localhost:8080/public/utils/whoami \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Replace:

• localhost:8080 with your deployment URL if the container is running elsewhere
• $ACCESS_KEY with your actual access key
• $SECRET_KEY with your actual secret key

A successful response will return information about your authenticated session:

{
  "userId": "...",
  "workspaceId": "...",
  "permissions": [...]
}

Available Endpoints

The API proxy provides access to Subnoto’s core functionality:

• Templates: list, list available templates
• Envelopes: create, create-from-template, send, list
• Documents: upload-document (simplified upload endpoint)
• Contacts: list
• Utils: whoami, workspace list

For complete API documentation and endpoint reference, visit the Subnoto API Documentation.

Important: All API endpoints must be accessed through the API proxy container. Do not call enclave.subnoto.com directly.

Uploading Documents

The API proxy provides a simplified /upload-document endpoint that handles document encryption and upload automatically. This is the recommended way to upload documents when using the API proxy.

Using the Upload Endpoint

curl -X POST http://localhost:8080/upload-document \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -F "workspaceUuid=your-workspace-uuid" \
  -F "envelopeTitle=My Document" \
  -F "file=@/path/to/document.pdf"

The endpoint accepts multipart/form-data with:

Field	Type	Required	Description
workspaceUuid	string	Yes	The UUID of the workspace to create the envelope in
envelopeTitle	string	Yes	The title of the envelope being created
file	file	Yes	The PDF document to upload (max 200 MB)

A successful response:

{
    "envelopeUuid": "uuid-of-created-envelope",
    "documentUuid": "uuid-of-uploaded-document",
    "message": "Document uploaded successfully"
}

Complete Upload Workflow Example

#!/bin/bash

# Configuration
PROXY_URL="http://localhost:8080"
ACCESS_KEY="your-access-key"
SECRET_KEY="your-secret-key"
FILE_PATH="path/to/document.pdf"
ENVELOPE_TITLE="Contract Agreement"

# Step 1: Get workspace UUID
echo "Fetching workspaces..."
WORKSPACE_RESPONSE=$(curl -s -X POST "$PROXY_URL/public/workspace/list" \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}')

WORKSPACE_UUID=$(echo "$WORKSPACE_RESPONSE" | grep -o '"uuid":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "Using workspace: $WORKSPACE_UUID"

# Step 2: Upload document
echo "Uploading document..."
UPLOAD_RESPONSE=$(curl -s -X POST "$PROXY_URL/upload-document" \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -F "workspaceUuid=$WORKSPACE_UUID" \
  -F "envelopeTitle=$ENVELOPE_TITLE" \
  -F "file=@$FILE_PATH")

ENVELOPE_UUID=$(echo "$UPLOAD_RESPONSE" | grep -o '"envelopeUuid":"[^"]*"' | cut -d'"' -f4)
echo "Envelope created: $ENVELOPE_UUID"

Example: Creating an Envelope from Template

# First, list available templates
curl http://localhost:8080/public/template/list \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'

# Then create an envelope from a template
curl http://localhost:8080/public/envelope/create-from-template \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceUuid": "your-workspace-uuid",
    "templateUuid": "template-uuid",
    "recipients": [
      {
        "type": "manual",
        "label": "customer",
        "email": "[email protected]",
        "firstname": "John",
        "lastname": "Doe"
      }
    ]
  }'

Example: Sending an Envelope

After creating an envelope (either via upload or from template), send it to recipients:

curl http://localhost:8080/public/envelope/send \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceUuid": "your-workspace-uuid",
    "envelopeUuid": "your-envelope-uuid",
    "customInvitationMessage": "Please review and sign this document."
  }'

Important Notes

Workspace UUID Requirement

The workspaceUuid parameter is required in requests to specify which workspace the resource belongs to. Best practice: Create a dedicated workspace for API-created envelopes to keep them organized separately from manually created envelopes.

Single Document Limitation

Currently, only one document per envelope is supported, both via the API and the user interface. This is a current limitation of the platform.

File Size Limits

The /upload-document endpoint accepts files up to 200 MB. For larger files or if you need more control over the upload process, you can use the SDK’s upload helper which handles encryption and uploads in chunks.

API Key Workspace Restrictions

API key workspace restrictions are not currently available. This feature will be added in a future release, allowing you to limit API keys to access only specific workspaces.

Troubleshooting