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
/api/v1/computer-sessions/{id}/accessAuthenticate 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
workspaceId | UUID string | Yes | The session's workspace. |
endUserId | string | Yes | Your external end-user ID for this session, not Weavz's internal identity ID. |
role | watch or control | Yes | Watch-only access or a human takeover capability. |
ttlSeconds | integer | No | Lifetime from 1 to 300 seconds; never extends the session's hard deadline. |
frameOrigin | HTTPS origin | No | Exact embedding application's origin. No path, wildcard, credentials, query or fragment. |
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
| Status | Meaning |
|---|---|
| 400 | Invalid session identifier, request, scope or embedding origin. |
| 401 | Missing or invalid API key. |
| 403 | The key cannot access the workspace or mint this access. |
| 404 | No matching hosted session for the supplied scope. |
| 409 | The session has stopped or cannot accept access in its current state. |
| 503 | The 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.