Sessions are the foundation of Uplink’s security and connection model. Understanding how to create, manage, and secure sessions is essential for production use.
What is a session? A session is an authenticated connection that allows your JavaScript code to communicate with mobile devices. Sessions are created programmatically using your organization API key and enable secure, real-time bidirectional communication.
const session = await uplink . session ( '<organization-api-key>' , { projectId: '<project-id>' , include: { ecdsa: true , ecdh: true } }) const client = await uplink . client . fromSession ( session )
Creating sessions Sessions are created programmatically in your code using your organization API key and project ID.
Get your credentials
In Uplink Console, navigate to Settings → API Keys to find your organization API key and project ID. Keep these credentials secure.
Create a session in code
Use the uplink.session() method to create a session with your credentials: const session = await uplink . session ( '<organization-api-key>' , { projectId: '<project-id>' , include: { ecdsa: true , ecdh: true } })
Connect a client to the session
Create a client from your session to interact with connected devices: const client = await uplink . client . fromSession ( session )
API keys and session security Sessions are authenticated using your organization API key, which provides:
Organization identity : Links sessions to your Uplink organizationProject scope : Sessions are associated with a specific project IDSecure communication : Encrypted connections between your code and devicesAccess control : Manage permissions through Console settings
Token security best practices
Treat API keys like passwords. Never commit them to source control or expose them in client-side code. // ✓ Good: Use environment variables const session = await uplink . session ( process . env . UPLINK_API_KEY , { projectId: process . env . UPLINK_PROJECT_ID , include: { ecdsa: true , ecdh: true } }) // ✗ Bad: Hardcoded credentials const session = await uplink . session ( 'sk_live_abc123...' , { projectId: 'proj_xyz789' , include: { ecdsa: true , ecdh: true } })
Create and destroy sessions as needed for your use case. For automated testing, create a new session for each test run and close it when complete. // Create session for a test const session = await uplink . session ( process . env . UPLINK_API_KEY , { projectId: process . env . UPLINK_PROJECT_ID , include: { ecdsa: true , ecdh: true } }) const client = await uplink . client . fromSession ( session ) // Run tests... // Always clean up await client . close ()
Use project-specific keys
Use different project IDs to isolate different environments or use cases. This helps organize your automations and manage access control.
Rotate API keys regularly
Regularly rotate API keys, especially after team member changes or security incidents. You can manage keys in the Uplink Console.
Session lifecycle Connection When you connect to a session, the client establishes a WebSocket connection to the Uplink relay server:
const session = await uplink . session ( '<organization-api-key>' , { projectId: '<project-id>' , include: { ecdsa: true , ecdh: true } }) const client = await uplink . client . fromSession ( session ) console . log ( 'Connected to session' ) // The client is now ready to interact with devices
Active session During an active session:
Devices can connect and disconnect
Browsers can be launched and managed
Commands are sent in real-time
Events are emitted for device state changes
client . on ( 'worker-connected' , ( device ) => { console . log ( 'Device joined session:' , device . address ) }) client . on ( 'worker-disconnected' , ( device ) => { console . log ( 'Device left session:' , device . address ) })
Closing a session Always close the client when you’re done to properly clean up resources:
// Clean up in order: pages, browsers, then client await page . close () await browser . close () await client . close ()
Session expiration Sessions end when:
The connection is closed by the client (client.close())
The session is terminated in the Console
The API key used to create the session is revoked
Network connectivity is lost
When a session expires, all connected devices are disconnected and browsers are closed. Plan for graceful handling of session expiration in long-running automations.
Multi-session patterns Load distribution For high-volume automation, distribute load across multiple sessions:
const sessions = await Promise . all ([ createAndConnectSession ( 'session-1' ), createAndConnectSession ( 'session-2' ), createAndConnectSession ( 'session-3' ) ]) // Round-robin device allocation const device = sessions [ nextIndex ++ % sessions . length ]
Next steps 
