Authentication

TL;DR

Cmdop SDK supports API key and OAuth authentication. API keys are recommended for server-side integrations — create them in the Dashboard under Settings. Use environment variables to keep keys out of code. API keys can have scoped permissions (machines:read, commands:execute, files:read/write). For browser apps, use OAuth with client ID.

How do I authenticate with an API key?

The primary authentication method:


import { Cmdop } from '@cmdop/sdk';
 
// Initialize the SDK client with your API key for server-side authentication
const client = new Cmdop({
  apiKey: 'your-api-key',
});

How do I get an API key?

Go to dashboard settings
Click “Create Token”
Set name and permissions
Copy the generated key

How do I use environment variables?


# Set the API key as an environment variable to keep it out of source code
export CMDOP_API_KEY=cmdop_xxx...


// Read the API key from the environment variable at runtime
const client = new Cmdop({
  apiKey: process.env.CMDOP_API_KEY,
});

How do I use OAuth for browser apps?

For browser applications with user login:


import { Cmdop } from '@cmdop/sdk';
 
// Initialize the SDK with OAuth client ID for browser-based authentication
const client = new Cmdop({
  clientId: 'your-client-id',
});
 
// Redirect the user to the Cmdop login page
await client.auth.login();
 
// Handle the OAuth callback after the user is redirected back to your app
const session = await client.auth.handleCallback();

How does token refresh work?

The SDK automatically handles token refresh:


// Configure the client with automatic token refresh to avoid expired sessions
const client = new Cmdop({
  apiKey: 'your-api-key',
  // Automatic refresh enabled by default — tokens are renewed before expiry
  autoRefresh: true,
});

How do I get current user info?

Get authenticated user info:


// Fetch the currently authenticated user's profile information
const user = await client.auth.me();
console.log(user.email);   // User's email address
console.log(user.name);    // User's display name
console.log(user.plan);    // Current subscription plan (free, pro, etc.)

What permissions can API keys have?

API keys can have scoped permissions:

Permission	Description
`machines:read`	List and view machines
`machines:write`	Modify machines
`commands:execute`	Execute commands
`files:read`	Read files
`files:write`	Write files

How do I check permissions?


// Retrieve the list of permissions granted to the current API key
const permissions = await client.auth.permissions();
console.log(permissions);
// Returns an array of permission strings: ['machines:read', 'commands:execute', ...]

What are the security best practices?

Never expose API keys in client code
Use environment variables
Set minimum required permissions
Rotate keys periodically
Use OAuth for user-facing apps

How do I use a backend proxy pattern?


// Next.js API Route — keeps the API key on the server, never exposed to the browser
export async function POST(req: Request) {
  // Initialize the SDK with a server-side environment variable
  const client = new Cmdop({
    apiKey: process.env.CMDOP_API_KEY,
  });
 
  // Parse the incoming request body for the target machine and command
  const { machineId, command } = await req.json();
  // Execute the command on the specified machine via the SDK
  const result = await client.commands.exec(machineId, command);
 
  // Return the command result to the frontend client
  return Response.json(result);
}