App sessions

Put the AI employee inside mobile, desktop and web apps without ever shipping the secret key.

For customers only. This channel serves the customers of the business (questions, sales, bookings) with your Brain, products and services. It is never an interface for the owner: it does not change settings, read Activities or take orders from the owner, even if someone says they are the owner. The owner talks to ORYKSA only in the official ORYKSA app, the dashboard and the browser extension. More

How it works

Your server calls POST /v1/sessions with the secret key and gets a client_token (oryk_cs_...) valid for 5 to 1440 minutes (default 60), bound to one conversation.
Your app receives only that token and talks to the /v1/client/* endpoints. It cannot read other conversations, change the agent or create keys.
When the token expires the API answers 401 session_expired: ask your server for a new one (the SDK does it for you with getToken).

Create a session (server)

POST/v1/sessions

import { Oryksa } from "@oryksa/sdk";
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY);

// e.g. GET /oryksa-token in YOUR backend, after your own user login
app.get("/oryksa-token", requireLogin, async (req, res) => {
  const s = await oryksa.createSession({
    conversationId: "user-" + req.user.id,   // one conversation per app user
    customerName: req.user.firstName,
    ttlMinutes: 60,
  });
  res.json({ token: s.client_token });
});

curl https://api.oryksa.com/v1/sessions \
  -H "Authorization: Bearer oryk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "user-4812", "customer_name": "Ana", "ttl_minutes": 60}'

{
  "object": "client_session",
  "client_token": "oryk_cs_6sCKXnHtZMpCXVO5LgpWbPF4jcSqpcOe",
  "conversation_id": "user-4812",
  "expires_at": "2026-09-24T10:41:07+00:00"
}

Use it in the app

import { OryksaClient, mountChat } from "@oryksa/sdk";

const client = new OryksaClient({
  // called again automatically when the token expires
  getToken: async () => (await fetch("/oryksa-token").then(r => r.json())).token,
});

// ready-made chat UI (same look as the website chat)
mountChat({ client, lang: "en" });

// or headless, with your own UI
const agent = await client.agent();          // name, photo, greeting, suggestions
const r = await client.send("How do I reset my password?");
console.log(r.reply);

# the app only uses the short-lived token
curl https://api.oryksa.com/v1/client/agent    -H "Authorization: Bearer oryk_cs_..."
curl https://api.oryksa.com/v1/client/chat     -H "Authorization: Bearer oryk_cs_..." \
     -H "Content-Type: application/json" -d '{"message": "Hi!"}'
curl https://api.oryksa.com/v1/client/messages -H "Authorization: Bearer oryk_cs_..."

Client endpoints

GET/v1/client/agent

Answer: agent name, photo, greeting, suggestions and subtitle per language, and whether voice replies are included.

POST/v1/client/chat

Send a message, same response as POST /v1/chat.

Before the AI answers a new customer, it asks for their name, email and phone in the conversation (the fields the owner keeps on in Connectors > Website chat > Visitor details). While it asks, the reply comes with "collecting": "name" | "email" | "phone" so your app can show the right keyboard; the customer simply answers in the chat and the first question is answered once the details are in.

GET/v1/client/messages

Messages of this conversation.

The client endpoints allow calls from any origin (CORS), so they work from web front-ends, React Native, Flutter, Electron and native apps. Limit: 30 requests per minute per session.

Teach the Brain about your app

import { Oryksa } from "@oryksa/sdk";
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY);

// Teach the AI employee about YOUR app, e.g. on every release (CI step)
await oryksa.learnApp({
  name: "FitTrack",
  agentName: "Nova",
  description: "FitTrack is a fitness app to log workouts and follow training plans.",
  languages: ["en", "pt"],
  screens: [
    { title: "Workouts", content: "Tap + to log a workout: running, cycling, gym or yoga." },
    { title: "Plans", content: "5K beginner (6 weeks), Half marathon (12 weeks). Plans are Premium." },
  ],
  settings: { units: "metric", sync: "Apple Health and Google Fit" },
  faq: [{ question: "How do I cancel Premium?", answer: "Settings > Subscription > Cancel." }],
});