Connect your app
App keys, the Integrate tab, and running workflows from your own backend.
Open an installed solution's Integrate tab (a new install opens on it). It has three parts:
- A go-live checklist: your backend has a key and has connected, only your sites can embed the assistant, each customer's spend is capped, and evals cover its behaviour.
- App keys: create, see when each was last used, revoke.
- Copy-ready code for Next.js, Node/Express, Python and plain HTTP, with this solution's id, workflows and entities filled in.
App keys (aks_…) are what your backend holds, never an organization API key. A key
reaches one solution through the apps API. By default it can:
- issue its end-user tokens;
- read and write its records;
- run its workflows.
Narrow it under App keys → What this key can do: records can be read/write, read-only or
disabled, and limited to selected entities. Workflow access and end-user token issuance are
separate switches. For a read-only reporting key, disable both switches too. Existing keys keep
full access; replacing and revoking a key changes its scope. Denied operations return 403.
Integrate → Data API lists record endpoints and lets you download an OpenAPI 3.1 specification as JSON or YAML, for the whole solution or as a selected key sees it. A read-only key's spec has no write operations. It describes record CRUD, filtering and paging; workflows and token issuance are separate APIs.
It's anonymous everywhere else, and refused if a web page sends it. A leaked key exposes one app, and revoking it stops it at once. Creating and revoking keys is audited.
With the TypeScript SDK (coming soon):
import { AktorServer } from "@aktor/sdk";
const aktor = new AktorServer({ installId: "sol-…", appKey: process.env.AKTOR_APP_KEY!, baseUrl: process.env.AKTOR_URL });
// The widget's data-token-url (it POSTs here after your own sign-in)
const { token } = await aktor.issueToken(user.id, { name: user.name });
// Run a workflow and wait for its result
const run = await aktor.run("triage", { subject: "Leak under the sink" });
Or, available today, plain HTTP:
| From your server, with the app key | |
|---|---|
POST /api/v1/apps/{id}/end-user-tokens | a token for one of your users |
GET/POST/PATCH/DELETE /api/v1/apps/{id}/records/{Entity}[/{recordId}] | the records API (Idempotency-Key, If-Match) |
POST /api/v1/apps/{id}/runs | { workflow, input?, data? } → run_id; an Idempotency-Key makes retries safe |
GET /api/v1/apps/{id}/runs/{runId}?wait=30 | waits for the result: status, summary, each stage's output |
GET /api/v1/apps/{id}/openapi.json or openapi.yaml | the records API spec restricted to this key; ?download=true returns it as a file |
Runs keep the workflow's budgets, safety rules and approvals, and each key can start 60 a minute.
The Python SDK, also coming soon, has the same client: AktorServer(install_id, app_key).run("triage", {...}).