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-from-template, send
• Utils: whoami

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

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"
      }
    ]
  }'