Sessions

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 project API key and enable secure, real-time bidirectional communication.

const session = await uplink.session('<project-api-key>', {
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)

Creating sessions

Sessions are created programmatically in your code using your project API key. The session is automatically scoped to the project the API key belongs to.

Get your API key

In Uplink Console, navigate to Settings → API Keys to find your project API key. Keep it secure.

Create a session in code

Use the uplink.session() method to create a session with your API key:

const session = await uplink.session('<project-api-key>', {
  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)

Deliver the session to your device

The session object exposes two URLs for connecting a device. Use the one that matches your integration:

Connect app
Native SDK

Display session.qrUrl as a QR code in your UI. When your user scans it, the Uplink Connect app opens and joins the session automatically.

import QRCode from 'qrcode'

const qrCodeImage = await QRCode.toDataURL(session.qrUrl)
// Render qrCodeImage in your UI

Deliver session.sessionUrl to your app through your own channel (push notification, deep link, API response, etc.), then pass it to the native SDK’s worker.connect method.

const sessionUrl = session.sessionUrl
// Deliver sessionUrl to your iOS or Android app

See the iOS SDK and Android SDK guides for how the app side consumes the URL.

API keys and session security

Sessions are authenticated using your project API key, which provides:

Project identity: Each API key belongs to exactly one project — sessions created with it are scoped to that project automatically.
Secure communication: Encrypted connections between your code and devices
Access control: Manage permissions through Console settings

Token security best practices

Keep API keys secret

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, {
  include: { ecdsa: true, ecdh: true }
})

// ✗ Bad: Hardcoded credentials
const session = await uplink.session('sk_live_abc123...', {
  include: { ecdsa: true, ecdh: true }
})

Manage session lifecycle

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, {
  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 separate API keys (and projects) 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('<project-api-key>', {
  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]

Introduction

Fundamentals

MCP Server

What is a session?

Creating sessions

API keys and session security

Token security best practices

Session lifecycle

Connection

Active session

Closing a session

Session expiration

Multi-session patterns

Load distribution

Next steps

Device management

Client API

​What is a session?

​Creating sessions

​API keys and session security

​Token security best practices

​Session lifecycle

​Connection

​Active session

​Closing a session

​Session expiration

​Multi-session patterns

​Load distribution

​Next steps

Device management

Client API

What is a session?

Creating sessions

API keys and session security

Token security best practices

Session lifecycle

Connection

Active session

Closing a session

Session expiration

Multi-session patterns

Load distribution

Next steps