Skip to main content
POST
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "port": 123,
  "authMode": "<string>",
  "expiresIn": "<string>"
}
'
{
  "sessionId": "<string>",
  "slug": "<string>",
  "publicUrl": "<string>",
  "ownerUrl": "<string>",
  "overlayScriptUrl": "<string>",
  "edgeUrl": "<string>",
  "sessionToken": "<string>",
  "expiresAt": "<string>",
  "username": "<string>",
  "password": "<string>"
}
Create a new Wormkey session with a unique slug and tokens for owner access.

​
Request Body

​
port
number
default:"3000"
The local port number your application is running on
​
authMode
string
default:"none"
Authentication mode for the session. Options: none, basicWhen set to basic, the response will include generated username and password credentials.
​
expiresIn
string
default:"24h"
Session expiration duration. Accepts formats like 30m (minutes) or 24h (hours)

​
Response

​
sessionId
string
required
Unique session identifier (format: sess_<token>)
​
slug
string
required
Human-readable session slug (format: adjective-noun-number)
​
publicUrl
string
required
Public URL where viewers can access the session
​
ownerUrl
string
required
Owner dashboard URL with authentication token included
​
overlayScriptUrl
string
required
URL to the overlay script for embedding session controls
​
edgeUrl
string
required
WebSocket edge URL for tunnel connection
​
sessionToken
string
required
Combined token for session authentication (format: slug.ownerToken)
​
expiresAt
string
required
ISO 8601 timestamp when the session expires
​
username
string
Basic auth username (only present when authMode is basic)
​
password
string
Basic auth password (only present when authMode is basic)

​
Example Request

curl -X POST https://control.wormkey.io/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "port": 3000,
    "authMode": "none",
    "expiresIn": "24h"
  }'

​
Example Response

{
  "sessionId": "sess_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "slug": "quiet-lime-42",
  "publicUrl": "https://wormkey.io/s/quiet-lime-42",
  "ownerUrl": "https://wormkey.io/.wormkey/owner?slug=quiet-lime-42&token=x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2",
  "overlayScriptUrl": "https://wormkey.io/.wormkey/overlay.js?slug=quiet-lime-42",
  "edgeUrl": "wss://wormkey.io/tunnel",
  "sessionToken": "quiet-lime-42.x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2",
  "expiresAt": "2026-03-04T15:30:00.000Z"
}

​
Example Response (Basic Auth)

{
  "sessionId": "sess_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "slug": "bold-mint-17",
  "publicUrl": "https://wormkey.io/s/bold-mint-17",
  "ownerUrl": "https://wormkey.io/.wormkey/owner?slug=bold-mint-17&token=x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2",
  "overlayScriptUrl": "https://wormkey.io/.wormkey/overlay.js?slug=bold-mint-17",
  "edgeUrl": "wss://wormkey.io/tunnel",
  "sessionToken": "bold-mint-17.x7y8z9a0b1c2d3e4f5g6h7i8j9k0l1m2",
  "expiresAt": "2026-03-04T15:30:00.000Z",
  "username": "worm",
  "password": "a1b2c3d4"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us