Skip to main content

​
Authentication Methods

Private Connect API supports two authentication methods:
  1. API Keys - For programmatic access and automation
  2. Session Tokens - For web application access (magic link authentication)

​
API Key Authentication

API keys are the primary authentication method for programmatic access. Include your API key in the x-api-key header: 
curl -H "x-api-key: pc_your_api_key_here" \
  https://api.privateconnect.co/v1/agents

​
Obtaining an API Key

Create an API key from the dashboard:
  1. Sign in to app.privateconnect.co
  2. Navigate to Settings → API Keys
  3. Click “Create API Key”
  4. Save the key securely - it’s only shown once
API keys are sensitive credentials. Never commit them to version control or share them publicly.

​
API Key Management

​
Create API Key

Create a new API key for your workspace. 
curl -X POST https://api.privateconnect.co/v1/api-keys \
  -H "Cookie: session=your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key"
  }'
Request Body:
​
name
string
required
Name for the API key (1-50 characters)
Response: 
{
  "id": "key_abc123",
  "name": "production-key",
  "key": "pc_live_1234567890abcdefghijklmnop",
  "prefix": "pc_live_1234",
  "createdAt": "2026-03-02T10:00:00.000Z"
}
Save the key value immediately - it cannot be retrieved later.

​
List API Keys

Retrieve all API keys for your workspace. 
curl https://api.privateconnect.co/v1/api-keys \
  -H "Cookie: session=your_session_token"
Response: 
[
  {
    "id": "key_abc123",
    "name": "production-key",
    "prefix": "pc_live_1234",
    "lastUsedAt": "2026-03-02T09:30:00.000Z",
    "createdAt": "2026-03-01T10:00:00.000Z",
    "isActive": true
  }
]
Full API keys are never returned in list operations, only the prefix for identification.

​
Get API Key Details

Retrieve details for a specific API key. 
curl https://api.privateconnect.co/v1/api-keys/key_abc123 \
  -H "Cookie: session=your_session_token"
Response: 
{
  "id": "key_abc123",
  "name": "production-key",
  "prefix": "pc_live_1234",
  "allowedIpRanges": ["10.0.0.0/8"],
  "lastUsedAt": "2026-03-02T09:30:00.000Z",
  "createdAt": "2026-03-01T10:00:00.000Z",
  "isActive": true
}

​
Update IP Restrictions

Restrict API key usage to specific IP ranges. 
curl -X PUT https://api.privateconnect.co/v1/api-keys/key_abc123/ip-restrictions \
  -H "Cookie: session=your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIpRanges": ["10.0.0.0/8", "192.168.1.0/24"]
  }'
Request Body:
​
allowedIpRanges
string[]
required
Array of CIDR ranges (e.g., ["10.0.0.0/8", "192.168.1.0/24"]). Empty array allows all IPs.

​
Revoke API Key

Permanently revoke an API key. 
curl -X DELETE https://api.privateconnect.co/v1/api-keys/key_abc123 \
  -H "Cookie: session=your_session_token"
Response: 
{
  "success": true
}
Revoking an API key is irreversible. All requests using the key will immediately fail.

​
Session Token Authentication

Session tokens are used for web application access via magic link authentication.

​
Register User

Create a new user account and workspace. 
curl -X POST https://api.privateconnect.co/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "workspaceName": "my-workspace"
  }'
Request Body:
​
email
string
required
User email address
​
workspaceName
string
required
Workspace name
Response: 
{
  "success": true,
  "message": "Verification email sent"
}

​
Login

Request a magic link login email. 
curl -X POST https://api.privateconnect.co/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
Response: 
{
  "success": true,
  "message": "Login link sent to your email"
}
Verify a magic link token (called automatically when clicking the email link). 
curl "https://api.privateconnect.co/v1/auth/verify?token=magic_token_here"
Response: Sets a session cookie and returns: 
{
  "success": true,
  "user": {
    "id": "user_123",
    "email": "[email protected]"
  },
  "workspace": {
    "id": "ws_456",
    "name": "my-workspace"
  },
  "isNewUser": false
}

​
Get Current User

Retrieve the currently authenticated user. 
curl https://api.privateconnect.co/v1/auth/me \
  -H "Cookie: session=your_session_token"

​
Logout

Invalidate the current session. 
curl -X POST https://api.privateconnect.co/v1/auth/logout \
  -H "Cookie: session=your_session_token"

​
Security Best Practices

  • Store API keys in environment variables or secret management systems
  • Never commit API keys to version control
  • Use different keys for development, staging, and production
  • Rotate keys periodically
  • Restrict API keys to known IP ranges when possible
  • Use CIDR notation for IP ranges (e.g., 10.0.0.0/8)
  • Update IP restrictions when infrastructure changes
  • Create a new API key before revoking the old one
  • Update all services to use the new key
  • Verify the new key works before revoking the old one
  • Monitor for any requests using the old key
  • Implement exponential backoff when rate limited
  • Cache responses when appropriate
  • Use webhooks instead of polling for real-time updates
  • Monitor rate limit headers to avoid limits

Build docs developers (and LLMs) love

Get started for freeTalk to us