IPC Endpoints

Complete reference for Flowsta Vault's local IPC API.

Flowsta Vault runs an HTTP server on 127.0.0.1:27777 that third-party apps use for identity linking, authentication, and backups. The @flowsta/holochain and @flowsta/auth-tauri SDKs wrap these endpoints, but you can call them directly if needed.

Base URL

http://127.0.0.1:27777

Vault tries ports 27777, 27778, 27779 in sequence if the previous port is in use.

Status

GET /status

Check if Vault is running and unlocked.

Response:

{
  "unlocked": true,
  "agent_pub_key": "uhCAk7JpEWfkiV...",
  "did": "did:flowsta:uhCAk...",
  "version": "0.1.0",
  "display_name": "John Doe",
  "profile_picture": "data:image/svg+xml;base64,..."
}

TIP

If the request fails to connect, Vault is not running. The running field is not part of the response — a successful response means Vault is running.

Agent Linking

POST /link-identity

Request an identity link. Shows an approval dialog in Vault.

Request:

{
  "app_name": "ChessChain",
  "client_id": "flowsta_app_abc123",
  "app_agent_pub_key": "uhCAk..."
}

Response (on approval):

{
  "success": true,
  "vault_agent_pub_key": "uhCAk...",
  "vault_signature": "base64-encoded-signature"
}

Response (on denial):

{
  "success": false,
  "error": "user_denied"
}

POST /revoke-identity

Notify Vault that an identity link has been revoked.

Request:

{
  "app_name": "ChessChain",
  "app_agent_pub_key": "uhCAk..."
}

GET /link-status

Check if a specific agent is still linked.

Query parameters: client_id, app_agent_pub_key

GET /link-status?client_id=flowsta_app_abc123&app_agent_pub_key=uhCAk...

Response:

{
  "linked": true,
  "app_name": "ChessChain"
}

Authentication (Tauri Apps)

POST /authenticate

Authenticate a Tauri desktop app. Shows an approval dialog in Vault with a 60-second timeout.

Request:

{
  "app_name": "Your Desktop App",
  "client_id": "flowsta_app_abc123",
  "challenge": "optional-challenge-to-sign",
  "reason": "Login to Your Desktop App"
}

The client_id and challenge fields are optional. The reason field is shown in the approval dialog.

Response:

{
  "success": true,
  "did": "did:flowsta:uhCAk...",
  "agent_pub_key": "uhCAk...",
  "signature": "base64-encoded-signature",
  "signed_at": 1709251200
}

The signature and signed_at fields are only present if a challenge was provided.

Backups

POST /backup

Store app data in the Vault's encrypted local storage.

Request:

{
  "client_id": "flowsta_app_abc123",
  "app_name": "ChessChain",
  "label": "latest",
  "content_type": "application/json",
  "data": { "your": "app data" }
}

Response:

{
  "success": true,
  "label": "latest",
  "data_size": 1024,
  "created_at": 1709251200
}

GET /backup/list

List all backups stored in Vault.

Response:

{
  "app_count": 1,
  "total_backups": 3,
  "total_size": 4096,
  "apps": [
    {
      "client_id": "flowsta_app_abc123",
      "app_name": "ChessChain",
      "backup_count": 3,
      "total_size": 4096,
      "last_backup_at": 1709251200
    }
  ]
}

POST /backup/retrieve

Retrieve a stored backup.

Request:

{
  "client_id": "flowsta_app_abc123",
  "label": "latest"
}

POST /backup/delete

Delete a stored backup.

Request:

{
  "client_id": "flowsta_app_abc123",
  "label": "latest"
}

Signing

POST /sign

Sign data with the Vault's agent key. Requires user approval.

Request:

{
  "type": "bytes",
  "bytes": "base64-encoded-data",
  "reason": "Sign this document"
}

The type field is required and must be "bytes" or "action". The reason field is shown in the approval dialog.

Response:

{
  "success": true,
  "signature": "base64-encoded-ed25519-signature",
  "agent_pub_key": "uhCAk..."
}

Future Feature

The /sign endpoint enables general-purpose signing use cases like authorship proofs, document signatures, and verifiable attestations. Full documentation will be added when this feature launches.

Error Responses

All endpoints return errors in this format:

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable description"
}

Error Code	HTTP Status	Description
vault_locked	403	Vault is locked
user_denied	403	User rejected the request
invalid_client_id	400	Client ID not registered
missing_client_id	400	No client_id provided
app_not_found	404	App ID not installed in Vault
api_unreachable	502	Cannot reach Flowsta API for verification

Next Steps

• @flowsta/holochain SDK - SDK that wraps these endpoints
• @flowsta/auth-tauri SDK - Desktop auth SDK
• Agent Linking - Identity attestation guide
• Building Holochain Apps - Integration guide