onairos-text-auth

Users authorize your app and share their Onairos personalization data from a text conversation — iMessage, RCS, SMS via Linq. One config, one webhook call. Onairos runs the entire auth flow inside the thread.

User:  Connect Onairos
Bot:   What email is on your Onairos account?
User:  [email protected] … 482913 … YES
→ your backend receives a data handoff for exactly what the user approved

Install

npm install onairos-text-auth

You need an Onairos developer API key with data:read, and your Linq webhook signing secret. Node ≥ 18. Framework-agnostic — the SDK takes plain { headers, rawBody, body } from any webhook route.

Quickstart

import express from 'express';
import { createTextAuthRelay } from 'onairos-text-auth';

const app = express();
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

const relay = createTextAuthRelay({
  onairosApiKey: process.env.ONAIROS_API_KEY,
  webhookSecret: process.env.LINQ_WEBHOOK_SECRET,
  appName: 'My App',
  requestedConfirmations: ['personality', 'preferences'],
  autoExchangeGrants: true
});

app.post('/linq/webhook', async (req, res) => {
  const result = await relay.handleWebhook({
    headers: req.headers,
    rawBody: req.rawBody,
    body: req.body,
    sendMessage: ({ chatId, text }) => myLinqClient.send(chatId, text)
  });

  if (result.handoff) {
    const data = await relay.fetchAuthorizedData({ handoff: result.handoff });
  }
  res.json({ ok: true });
});

Fastify, Next.js, and custom-trigger variants: examples/.

API

| Method | Purpose | |---|---| | createTextAuthRelay(config) | One-time setup | | relay.handleWebhook({...}) | Verify, dedupe, relay, reply, auto-exchange | | relay.startConnect({ body, sendMessage }) | Start the flow from your own pitch wording | | relay.exchangeGrant({ grantId }) | Fresh 1-hour data token, any time within 90 days | | relay.fetchAuthorizedData({ handoff }) | The personalization payload |

Grants are revocable (user texts disconnect). Consent can never be triggered programmatically — YES/NO and email/code only ever come from the user's real messages.

Full reference for humans and AI agents: llms.txt.

LLM-agent apps

If a model runs your thread, add the companion package onairos-text-auth-mcp: a deterministic bridge (flow messages never route through your model) plus six MCP tools.

License

Apache-2.0 · docs.onairos.uk · [email protected]