Skip to main content

​
Create share

Share a credential with another PassAgent user. Requires step-up authentication (recent login within 5 minutes). 
POST /api/sharing
Authentication: Required CSRF: Required Step-up auth: 5 minutes Rate limits:
  • 20 shares per minute per user
  • Maximum 10 shares per password
  • Maximum 50 active shares per user
Request body: 
{
  "accountId": "pwd_12345",
  "recipientEmail": "friend@example.com",
  "permission": "read",
  "expiresAt": "2026-04-04T00:00:00Z",
  "wrapped_vault_key_invite": "base64-wrapped-key",
  "invite_token_salt": "base64-salt"
}
FieldTypeRequiredDescription
accountIdstringYesPassword entry ID to share
recipientEmailstringYesRecipient’s email address
permissionstringNoread (default) or write
expiresAtISO-8601NoExpiration timestamp
wrapped_vault_key_invitestringNoWrapped key for invite-based sharing
invite_token_saltstringNoSalt for invite token generation
Response 201 Created: 
{
  "success": true,
  "share": {
    "id": "shr_abc123",
    "account_id": "pwd_12345",
    "owner_id": "usr_owner",
    "recipient_id": null,
    "recipient_email": "friend@example.com",
    "status": "pending",
    "permission": "read",
    "expires_at": "2026-04-04T00:00:00Z",
    "created_at": "2026-03-04T12:00:00Z"
  }
}
Errors:
  • 409 Conflict — already shared with this email, or self-sharing attempt
  • 429 Too Many Requests — share limits exceeded

​
List shares

GET /api/sharing
Authentication: Required Rate limit: 30 requests per 60 seconds per user Query parameters:
ParameterTypeRequiredDescription
typestringYesowned (shares you created) or received (shares others sent you)
accountIdstringNoFilter by password ID
Response 200 OK: 
{
  "shares": [
    {
      "id": "shr_abc123",
      "account_id": "pwd_12345",
      "owner_id": "usr_owner",
      "recipient_id": "usr_recipient",
      "recipient_email": "friend@example.com",
      "status": "active",
      "permission": "read",
      "expires_at": "2026-04-04T00:00:00Z",
      "accepted_at": "2026-03-04T13:00:00Z",
      "account": {
        "id": "pwd_12345",
        "name": "Netflix",
        "website": "netflix.com",
        "url": "https://netflix.com",
        "encrypted_data": "base64...",
        "wrapped_item_key": "base64..."
      }
    }
  ],
  "setup_required": false
}
The encrypted_data and wrapped_item_key fields are only included for received shares, allowing the recipient to decrypt the credential client-side.

​
Update share

PATCH /api/sharing/{id}
Authentication: Required CSRF: Required Rate limit: 30 requests per 60 seconds per user Request body: 
{
  "status": "active",
  "permission": "write"
}
  • Owners can revoke shares or change permissions
  • Recipients can accept pending shares (set status: "active")

​
Delete share

DELETE /api/sharing/{id}
Authentication: Required (owner only) CSRF: Required Rate limit: 30 requests per 60 seconds per user

​
Log share view

Record when a recipient views or copies a shared credential. 
POST /api/sharing/{id}/view
Authentication: Required (recipient only) Rate limit: 30 requests per 60 seconds per user Request body: 
{
  "action": "password_viewed"
}
ActionDescriptionNotifies owner
password_viewedRecipient viewed the credentialYes
password_copiedRecipient copied the credentialNo

​
Session sharing

Share authenticated browser sessions without exposing credentials.

​
Create session share

POST /api/session-shares
Authentication: Required CSRF: Required Step-up auth: 300 seconds Rate limit: 10 sessions per hour per user Request body: 
{
  "accountId": "pwd_12345",
  "decryptedUsername": "john@example.com",
  "decryptedPassword": "SecurePass123",
  "accessType": "full",
  "durationMinutes": 15,
  "maxViewers": 3,
  "loginMethod": "ai_agent",
  "viewOnly": false,
  "watermarkEnabled": true,
  "scheduledStart": "2026-03-04T15:00:00Z"
}
FieldTypeRequiredDescription
accountIdstringYesAssociated vault entry
decryptedUsernamestringYesPlaintext username (encrypted for storage)
decryptedPasswordstringYesPlaintext password (encrypted for storage)
accessTypestringNofull or view_only
durationMinutesintegerNoSession length (default: 15)
maxViewersintegerNoMax concurrent viewers (default: 1)
loginMethodstringNoai_agent (automated login) or manual
viewOnlybooleanNoRead-only access
watermarkEnabledbooleanNoShow watermark overlay
scheduledStartISO-8601NoSchedule session for later
Response 201 Created: 
{
  "id": "sess_12345",
  "shareToken": "abc123def456",
  "shareUrl": "/s/abc123def456",
  "status": "login_in_progress",
  "estimatedCostCents": 150,
  "expiresAt": "2026-03-04T12:15:00Z",
  "serviceName": "Netflix",
  "loginMethod": "ai_agent"
}
The shareToken is hashed with SHA-256 before storage. It is returned only once during creation — store it securely.

​
Watch session progress (SSE)

GET /api/session-shares/{id}/status
Authentication: Required (owner only) Content-Type: text/event-stream Polls every 2 seconds for up to 5 minutes. 
event: status
data: {"type":"status","status":"login_in_progress","currentViewers":0}

event: status
data: {"type":"status","status":"active","livePreviewUrl":"https://...","currentViewers":1}

event: complete
data: {"type":"complete","status":"active","livePreviewUrl":"https://..."}

​
Manage session

PATCH /api/session-shares/{id}
Pause, resume, revoke, extend duration, or toggle watermark. 
DELETE /api/session-shares/{id}
Revoke and terminate the session immediately.