Authentication
The recommended standalone SDK flow is to create a personal access token in the OLO web app and pass that token to the SDK.
Note: In the SDK Playground, authentication is automatic. Playground browser sessions use the existing web login, and appliance-executed Python does not need standalone credentials unless you are explicitly connecting to additional appliances from your code.
Billing: Standalone SDK access outside the Playground requires a paid plan. Free users can still use the SDK inside the in-app Playground, but external getUserRobots() and subsequent standalone SDK flows may return STANDALONE_SDK_REQUIRED.
Security model: Auth source classification for billing is server-derived from credential provenance (cookie session, personal token, appliance key, bearer session token). Client headers like x-olo-auth-source are treated as hints and do not override standalone billing enforcement decisions.
Important: Username/password login is retained for compatibility, but two-factor-enabled accounts should use a personal access token instead of embedding credentials in code.
Personal access token setup
const oloClient = new OLOClient({
apiUrl: 'https://app.olo-robotics.com',
authToken: 'olo_pat_your_token_here'
});
const appliances = await oloClient.getUserRobots();authenticate(username, password)
Authenticate user with username and password.
Parameters:
username(string) - Username or emailpassword(string) - Password
Returns: Promise<Object> - Authentication result with token
If the account requires two-factor authentication, standalone SDK login will not complete the second step. In that case, create and use a personal access token instead.
// Create a new client instance for authentication
const oloClient = new OLOClient({
apiUrl: 'https://app.olo-robotics.com'
});
const result = await oloClient.authenticate('myuser@example.com', 'mypassword');
console.log('Auth token:', result.token);getUserRobots()
Get list of appliances for the authenticated user. Use either authenticate() first or set a personal access token on the client.
Returns: Promise<Array> - Array of appliance objects
Billing behavior: On accounts without standalone SDK entitlement, this call returns an error with code STANDALONE_SDK_REQUIRED.
// Must authenticate first
await oloClient.authenticate('myuser@example.com', 'mypassword');
const appliances = await oloClient.getUserRobots();
console.log('Available appliances:', appliances);getAuthToken()
Get the stored user session token used by standalone REST calls.
Returns: string|null - Current user session token
const token = oloClient.getAuthToken();
console.log('Current token:', token);clearAuth()
Clear authentication token.
oloClient.clearAuth();Complete Authentication Flow
Full example showing token-based standalone authentication, robot discovery, and connection:
// Complete token-based connection example
async function connectToRobot(authToken, serverUrl = 'https://app.olo-robotics.com') {
try {
const oloClient = new OLOClient({
apiUrl: serverUrl,
authToken
});
// Step 1: Get available robots
const robots = await oloClient.getUserRobots();
console.log(`Found ${robots.length} robots:`, robots);
if (robots.length === 0) {
throw new Error('No robots available for this user');
}
// Step 2: Connect to first robot
const robot = robots[0];
await oloClient.connect(robot.id, oloClient.getAuthToken());
console.log(`Connected to robot: ${robot.name || robot.id}`);
return { oloClient, robot };
} catch (error) {
console.error('Token-based connection failed:', error);
throw error;
}
}
// Usage
const { oloClient, robot } = await connectToRobot('olo_pat_your_token_here');Connecting to Multiple Appliances in SDK Playground
In the SDK Playground, you can connect to multiple appliances simultaneously by creating additional client instances. The pre-configured oloclient remains connected to your selected appliance, while you can create new clients for additional appliances.
Note: Each appliance connection can access multiple robots via ROS namespaces. This section is about connecting to different appliances, not different robots within the same ROS domain.
// JavaScript version: Control multiple appliances
const oloClient2 = new OLOClient({
apiUrl: 'https://app.olo-robotics.com'
});
// Authenticate
await oloClient2.authenticate('your-username', 'your-password');
const robots = await oloClient2.getUserRobots();
// Connect to second appliance
await oloClient2.connect(robots[1].id, oloClient2.getAuthToken());
// Control both appliances
await oloClient.core.sendVelocity('/cmd_vel', { linear: 0.5, angular: 0 });
await oloClient2.core.sendVelocity('/cmd_vel', { linear: -0.5, angular: 0 });
// Stop both
await oloClient.core.stopRobot();
await oloClient2.core.stopRobot();