Build an integration.

https://www.localhostdevs.com/connect
  ?handle=<the user's localhostdevs handle>
  &app=<your app's display name>
  &return=<absolute URL on your side that handles the code>

Parameters

What the user sees

A small consent card with your app name, a short description of the permissions, and two buttons:

• Allow → we generate a single-use code and redirect them to your return URL with ?code=… appended.
• Deny → we redirect them to your return URL with ?error=denied.

curl -X POST https://www.localhostdevs.com/api/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"code":"<code from the redirect>","app":"<your app name>"}'

Response

{
  "ok": true,
  "token": "lhdapp_XXXXXXXXXXXXXXXX...",
  "userId": "01J...",
  "userHandle": "qa"
}

Error cases

• 401 unauthorized — code is unknown, already-redeemed, or expired (5 min).
• 400 validation_error — body is missing code or app.

// Store securely — these are scoped to a single user × app pair.
await db.appTokens.insert({ userId, token, app: 'MyApp' });

// Later, when MyApp wants to dispatch on behalf of this user:
const res = await fetch(
  `https://www.localhostdevs.com/api/v1/bots/${handle}/dispatch`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ command: 'ping', args: {} }),
  },
);

Storage rules

• Tokens are long-lived — they don't expire on a schedule. They die when the user revokes them from their /account/tokens page, or when your code calls DELETE /api/v1/app-tokens/{id} (coming soon).
• Store server-side, encrypted at rest. Never put a token in browser storage / localStorage — anything that runs in the user's browser tab can read it.
• Detect revocation lazily: if any API call returns 401 unauthorized, throw the token away and re-run the Connect flow.

import express from 'express';
import { randomUUID } from 'node:crypto';

const app = express();
const APP_NAME = 'MyApp';
const RETURN_URL = 'https://myapp.example.com/connect/callback';

// 1. Start the flow. User clicks "Connect to localhostdevs" in your UI.
app.get('/connect/start', (req, res) => {
  const handle = req.query.handle; // collected from the user's profile / form
  const state = randomUUID();      // CSRF guard — store this in their session
  req.session.connectState = state;

  const params = new URLSearchParams({
    handle,
    app: APP_NAME,
    return: `${RETURN_URL}?state=${state}`,
  });
  res.redirect(`https://www.localhostdevs.com/connect?${params}`);
});

// 2. Handle the callback. Code in the URL, exchange it server-side.
app.get('/connect/callback', async (req, res) => {
  if (req.query.state !== req.session.connectState) {
    return res.status(400).send('state mismatch');
  }
  if (req.query.error === 'denied') {
    return res.send('User declined.');
  }
  const code = req.query.code;
  if (!code) return res.status(400).send('missing code');

  const r = await fetch('https://www.localhostdevs.com/api/v1/auth/exchange', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code, app: APP_NAME }),
  });
  const data = await r.json();
  if (!data.ok) return res.status(500).send('exchange failed');

  // 3. Persist. Now you have a token good for calling bots as this user.
  await db.appTokens.insert({
    appUserId: req.session.userId,
    lhdUserId: data.userId,
    lhdToken: data.token,
  });

  res.redirect('/dashboard');
});

When they click Disconnect:

• The token is marked revoked in our DB — every subsequent API call returns 401.
• We don't webhook your app. You discover the revocation on the next 401 and re-run the Connect flow (or, more politely, prompt the user before doing so).
• Tokens are per-user × per-app. Revoking MyApp doesn't affect any other connections the user has.