P
Proxies.ai

Shares API

Create and revoke secure proxy shares.

Secure shares are expiring, use-limited, TLS-terminated proxy capabilities. Every share must name a vault — the share can only reach hosts bound to that vault. All endpoints require authentication with shares:read or shares:write scope.

List Shares

GET/api/proxies/:id/shares
bash
curl https://proxies.ai/api/proxies/proxy-id/shares \
  -H "Authorization: Bearer cifp_your_api_key"

Create Share

POST/api/proxies/:id/shares
bash
curl -X POST https://proxies.ai/api/proxies/proxy-id/shares \
  -H "Authorization: Bearer cifp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "vaultId": "vault-id",
    "expiresAt": "2026-07-19T20:00:00Z",
    "maxUses": 1,
    "visibility": "public"
  }'

The response includes a url field with the bearer-token proxy URL. This URL is only returned once — store it securely.

FieldRequiredDescription
vaultIdYesVault whose host bindings restrict the share's egress
expiresAtYesISO-8601 expiry timestamp (max 30 days)
maxUsesYesMaximum accepted requests (1–10,000)
visibilityNopublic (default) or private
portNoDedicated port (10000–65535, auto-assigned if omitted)

Share Usage

GET/api/proxies/:id/shares/:shareId/usage

Returns per-request usage logs: method, path, status code, bytes, duration, timestamp.

Revoke Share

DELETE/api/shares/:shareId
bash
curl -X DELETE https://proxies.ai/api/shares/share-id \
  -H "Authorization: Bearer cifp_your_api_key"

# Returns 204 No Content

Revocation removes the Fly service mapping and closes the dedicated listener immediately. The share URL stops accepting connections within seconds.

Using a Share URL

bash
HTTPS_PROXY='https://share:<token>@proxy-host:port' \
  curl https://api.openai.com/v1/models

The share URL is a bearer token. Send it through a secure channel and never place it in source code, issue trackers, shell history, or logs.

Enforcement

  • Fly terminates TLS before forwarding to the per-share gateway
  • Constant-time token validation with crypto/subtle
  • Atomic use-count increment — denied vault hosts do not consume a use
  • Hard expiry and manual revocation checked on every request
  • Dedicated Squid listener closes after final use and within one minute of expiry
  • Traffic is chained to local Squid — firewall rules, blocklists, and ICAP still apply

Required Scopes

ScopeEndpoints
shares:readGET shares, GET share usage
shares:writePOST shares, DELETE shares