Skip to main content

​
Overview

Shares provide secure, time-limited access to services via shareable links. The Shares API enables creating shares, managing access control, and monitoring usage.

​
Create Share

Create a shareable link for a service. 
curl -X POST https://api.privateconnect.co/v1/services/svc_123/shares \
  -H "x-api-key: pc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "contractor-access",
    "description": "Temporary database access for Q1 audit",
    "expiresIn": "7d",
    "allowedPaths": ["/api/*"],
    "allowedMethods": ["GET", "POST"],
    "rateLimitPerMin": 100
  }'
Path Parameters:
​
serviceId
string
required
ID of the service to share
Request Body:
​
name
string
required
Share name (1-100 characters)
​
description
string
Share description (max 500 characters)
​
expiresIn
string
Expiration duration: 1h, 24h, 7d, 30d, never
​
allowedPaths
string[]
Allowed URL paths (supports wildcards). Example: ["/api/*", "/public/*"]
​
allowedMethods
string[]
HTTP methods to allow: GET, POST, PUT, PATCH, DELETE
​
rateLimitPerMin
number
Rate limit per minute (1-1000)
Response: 
{
  "success": true,
  "share": {
    "id": "share_123",
    "token": "share_tok_1234567890abcdefghijklmnop",
    "name": "contractor-access",
    "expiresAt": "2026-03-09T10:00:00.000Z",
    "shareUrl": "https://link.privateconnect.co/shared/share_tok_1234567890abcdefghijklmnop"
  }
}
Save the shareUrl - it’s the link you’ll send to users. The token cannot be retrieved later.

​
List Shares

Retrieve all shares for a service. 
curl https://api.privateconnect.co/v1/services/svc_123/shares \
  -H "Cookie: session=your_session_token"
Response: 
{
  "shares": [
    {
      "id": "share_123",
      "name": "contractor-access",
      "description": "Temporary database access for Q1 audit",
      "tokenPreview": "share_tok_123...",
      "expiresAt": "2026-03-09T10:00:00.000Z",
      "revokedAt": null,
      "isActive": true,
      "createdAt": "2026-03-02T10:00:00.000Z",
      "lastAccessedAt": "2026-03-02T11:00:00.000Z",
      "accessCount": 42,
      "shareUrl": "/shared/share_tok_1234567890abcdefghijklmnop"
    }
  ]
}
Full tokens are never returned in list operations, only a preview prefix for identification.

​
Revoke Share

Revoke a share, making it no longer usable. 
curl -X DELETE https://api.privateconnect.co/v1/shares/share_123 \
  -H "Cookie: session=your_session_token"
Response: 
{
  "success": true
}
Revoking a share is immediate. All active users will lose access.

​
Get Share Info

Retrieve public information about a share. No authentication required. 
curl https://api.privateconnect.co/v1/shared/share_tok_1234567890abcdefghijklmnop/info
Response: 
{
  "name": "contractor-access",
  "description": "Temporary database access for Q1 audit",
  "expiresAt": "2026-03-09T10:00:00.000Z",
  "workspaceName": "acme-corp",
  "service": {
    "name": "prod-db",
    "targetHost": "localhost",
    "targetPort": 5432,
    "protocol": "tcp"
  }
}
This endpoint provides minimal information about the share without requiring authentication.

​
Get Access Logs

Retrieve access logs for a share. 
curl https://api.privateconnect.co/v1/shares/share_123/logs \
  -H "Cookie: session=your_session_token"
Response: 
{
  "logs": [
    {
      "id": "log_123",
      "shareId": "share_123",
      "ipAddress": "203.0.113.42",
      "userAgent": "Mozilla/5.0...",
      "path": "/api/users",
      "method": "GET",
      "statusCode": 200,
      "latencyMs": 45,
      "timestamp": "2026-03-02T11:00:00.000Z"
    }
  ]
}

​
Share Proxying

When a user accesses a share URL, requests are proxied through the Private Connect hub to the target service.

​
HTTP/HTTPS Proxying

For HTTP/HTTPS services, all requests are proxied: 
# User accesses share URL
curl https://share_tok_abc123.privateconnect.co/api/users

# Proxied to target service
GET /api/users
Host: localhost:3000
x-forwarded-for: 203.0.113.42
x-shared-access: true
x-share-name: contractor-access
HTML responses include a Private Connect branding banner for share attribution.

​
Database Query Execution

For database services (PostgreSQL, MySQL, MongoDB, Redis), execute queries via the API: 
curl -X POST https://api.privateconnect.co/api/shared/share_tok_abc123/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users LIMIT 10"
  }'
Request Body:
​
query
string
required
SQL query to execute (max 10,000 characters)
Response: 
{
  "columns": ["id", "email", "created_at"],
  "rows": [
    { "id": "1", "email": "[email protected]", "created_at": "2026-03-01" }
  ],
  "rowCount": 10
}
Query execution is rate limited to 30 queries per minute per share token.

​
Access Control

​
Path Restrictions

Restrict access to specific URL paths: 
{
  "allowedPaths": [
    "/api/public/*",    // Allow all under /api/public/
    "/health",          // Allow exact path
    "/docs/*"           // Allow all documentation
  ]
}
Wildcard patterns:
  • * matches any characters within a path segment
  • /* matches all paths under a directory
  • Exact matches require full path

​
Method Restrictions

Limit HTTP methods: 
{
  "allowedMethods": ["GET", "POST"]
}
This prevents PUT, PATCH, and DELETE requests, providing read-only access with limited write capabilities.

​
Rate Limiting

Set custom rate limits per share: 
{
  "rateLimitPerMin": 100
}
Default rate limits by route:
  • /shared/:token/* - 5,000 requests/minute (for web apps with many assets)
  • /api/shared/:token/query - 30 queries/minute (for database queries)
When rate limited: 
{
  "error": "Too many requests",
  "message": "Rate limit exceeded for this share",
  "retryAfter": 60
}

​
Share Expiration

Shares can have time-based expiration:
Ideal for temporary demos or quick testing sessions.
Good for daily testing access or short-term collaboration.
Suitable for weekly sprints or short projects.
For longer-term contractor access or extended testing.
Permanent share until manually revoked. Use with caution.
Expired shares automatically become inactive and return a 403 Forbidden error.

​
Share Subdomains

Shares can be accessed via custom subdomains: 
https://share_tok_abc123.privateconnect.co
The subdomain is the share token, making URLs cleaner and easier to share.

​
Monitoring and Analytics

Track share usage via access logs:
  • IP addresses - See who’s accessing the share
  • User agents - Identify browsers and tools
  • Request paths - Monitor which endpoints are accessed
  • Status codes - Track errors and successful requests
  • Latency - Measure performance
  • Access count - Total number of requests
  • Last accessed - Most recent activity timestamp
Set up webhooks to receive real-time notifications: 
{
  "event": "share.accessed",
  "data": {
    "shareId": "share_123",
    "shareName": "contractor-access",
    "ipAddress": "203.0.113.42",
    "timestamp": "2026-03-02T11:00:00.000Z"
  }
}

​
Use Cases

Client Demos

Share development environments with clients for feedback without VPN access.

External Audits

Provide time-limited database access to auditors with query logging.

API Testing

Share staging APIs with external testers or integration partners.

Team Collaboration

Enable temporary access for contractors or remote team members.

​
Best Practices

  1. Set expiration - Always use time-limited shares unless permanent access is required
  2. Restrict paths - Limit access to only necessary endpoints
  3. Monitor logs - Regularly review access logs for suspicious activity
  4. Revoke promptly - Remove access when collaboration ends
  5. Use rate limits - Protect services from abuse with appropriate rate limits
  6. Read-only when possible - Use allowedMethods: ["GET"] for read-only access

Build docs developers (and LLMs) love

Get started for freeTalk to us