Skip to content
Weavz
Menu

Computer Access

Issue short-lived watch or control access for a hosted computer from an authenticated customer backend.

Use this endpoint from a trusted backend to issue a watch or human control link for an existing hosted Computer Control session. Create, operate and end computers through integration actions.

Create access

POST/api/v1/computer-sessions/{id}/access

Authenticate with Authorization: Bearer wvz_your_api_key. The key and session must belong to the same organization, and a workspace-scoped key must include the session's workspace. Your backend must also authenticate its user and authorize that user's access to this session.

FieldTypeRequiredMeaning
workspaceIdUUID stringYesThe session's workspace.
endUserIdstringYesYour external end-user ID for this session, not Weavz's internal identity ID.
rolewatch or controlYesWatch-only access or a human takeover capability.
ttlSecondsintegerNoLifetime from 1 to 300 seconds; never extends the session's hard deadline.
frameOriginHTTPS originNoExact embedding application's origin. No path, wildcard, credentials, query or fragment.
bash
curl -X POST https://platform.weavz.io/api/v1/computer-sessions/7df5c03e-4df5-4b5f-95a7-5277d8f972db/access \
  -H 'Authorization: Bearer wvz_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "endUserId": "customer_123",
    "role": "watch",
    "ttlSeconds": 300,
    "frameOrigin": "https://app.example.com"
  }'

The response contains sessionId, role, viewerUrl, expiresAt and, when requested, the canonical frameOrigin. viewerUrl contains a credential in its fragment. Deliver it only to the intended viewer; do not log it or return a control URL to an agent.

Errors and recovery

StatusMeaning
400Invalid session identifier, request, scope or embedding origin.
401Missing or invalid API key.
403The key cannot access the workspace or mint this access.
404No matching hosted session for the supplied scope.
409The session has stopped or cannot accept access in its current state.
503The computer service cannot complete the request.

An access link is not a session extension. Obtain a fresh link to reconnect after expiry. Computer data-plane URLs are returned capabilities, not additional customer management APIs; use the returned viewer URL rather than constructing one.