Autentikasi

API memakai token sesi atau API key. Anda mendapatkan sesi dengan login, lalu mengirimnya sebagai cookie (browser) atau bearer token; server dan skrip bisa memakai API key.

Login

POST /auth/login
Content-Type: application/json

{ "email": "anda@contoh.com", "password": "password-anda" }

Responsnya { "userId": "…", "accountType": "client", "tenantId": "…" } dan memasang cookie HttpOnly bernama lex_session (SameSite=Lax, Secure di production). Sesi berlaku 7 hari secara bawaan. POST /auth/logout mengakhiri sesi (204).

Pengguna baru bisa membuat akun dengan POST /auth/register (email, password, serta displayName dan workspaceName opsional). Setiap akun client mendapat satu workspace pribadi.

Tipe akun

Lex punya dua sistem akun terpisah yang bisa Anda integrasikan. Setiap aplikasi hanya bisa login dengan tipe akunnya sendiri, dan satu email boleh punya satu akun untuk tiap tipe dengan password berbeda.

Tipe akun	Aplikasi	x-lex-client	Cookie sesi	Pendaftaran
client	Aplikasi Lex	nilai lain apa pun (mis. aplikasi-saya)	lex_session	POST /auth/register
contributor	Platform kontributor (developer Mini Program)	contributor-dashboard	lex_contributor_session	POST /auth/register

Header x-lex-client pada /auth/login dan /auth/register menentukan tipe akunnya. Setiap endpoint hanya untuk satu tipe akun: endpoint client menjawab 403 FORBIDDEN ("A Lex client account is required.") untuk sesi contributor, sedangkan /contributor/* menolak sesi client.

Dari browser

Kirim cookie di setiap request, dan tambahkan header client di setiap request yang mengubah sesuatu (POST, PUT, PATCH, DELETE):

const API = 'https://api.lexcetha.com/api/v1';

async function api(path: string, init: RequestInit = {}) {
  const res = await fetch(`${API}${path}`, {
    ...init,
    credentials: 'include',
    headers: { 'content-type': 'application/json', 'x-lex-client': 'aplikasi-saya', ...init.headers },
  });
  if (!res.ok) throw (await res.json()).error;
  return res.status === 204 ? undefined : res.json();
}

Header x-lex-client melindungi sesi cookie dari cross-site request forgery: form HTML biasa di situs lain tidak bisa menambahkannya, jadi tidak bisa mengubah apa pun. Request tanpa header ini mendapat 403 FORBIDDEN ("Missing client header").

Origin yang diizinkan

Browser hanya bisa memanggil API dari origin yang ada di allowlist CORS-nya. Aplikasi-aplikasi Lex sudah terdaftar. Untuk memanggil API dari aplikasi web Anda sendiri, minta tim platform menambahkan origin Anda.

API key (disarankan untuk server)

Untuk server, job backend, atau CI, pakai API key, bukan password.

1. Di platform kontributor (platform.lexcetha.com), pindahkan sidebar ke API Integration.
2. Tautkan workspace Lexcetha Anda: masuk dengan akun aplikasi Lexcetha Anda. Key bertindak sebagai akun itu, di workspace-nya.
3. Buat key dengan scope yang benar-benar dibutuhkan saja, dan kedaluwarsa opsional. Key (lx_…) hanya ditampilkan sekali; Lexcetha hanya menyimpan hash-nya.

Kirim sebagai token bearer:

curl https://api.lexcetha.com/api/v1/bots \
  -H "Authorization: Bearer lx_…"

Scope	Endpoint
bots:read / bots:write	/bots, /desktop-sessions, /skills
chat:read / chat:write	/agent-runs, /chats, /conversations, /attachments, /speech, /transcriptions, /realtime-calls
approvals:read / approvals:write	/approvals
connectors:read / connectors:write	/integrations, /connector-providers, /connector-connections, /catalog/connectors
schedules:read / schedules:write	/schedules, /scheduled-runs
documents:read / documents:write	/documents, /document-folders, /document-proposals
catalog:read	/catalog, /plugins, /mini-programs
usage:read	/usage

read mencakup GET; write mencakup sisanya dan sudah termasuk read. Semua key boleh memanggil GET /me dan GET /tenants/current. Key tidak pernah bisa mengakses login, saved login, memori, ekspor, atau penghapusan akun: semuanya menjawab 403 FORBIDDEN, begitu juga endpoint di luar scope key ("This API key does not have the bots:write scope."). Key yang dicabut, kedaluwarsa, atau tidak dikenal mendapat 401 UNAUTHENTICATED. Melepas tautan workspace mencabut semua key. Aksi lewat key mengikuti persetujuan yang sama seperti di aplikasi.

Dari server atau skrip

Ambil token sesi dari header Set-Cookie respons /auth/login, lalu kirim sebagai bearer token. Request bearer tidak perlu header client.

TOKEN=$(curl -s -D - -o /dev/null -X POST https://api.lexcetha.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"anda@contoh.com","password":"password-anda"}' \
  | sed -n 's/^set-cookie: lex_session=\([^;]*\).*/\1/ip')

curl https://api.lexcetha.com/api/v1/bots -H "Authorization: Bearer $TOKEN"

Untuk akun contributor, tambahkan -H 'x-lex-client: contributor-dashboard' pada request login dan ambil lex_contributor_session.

Jaga kerahasiaan token: siapa pun yang memegangnya bertindak sebagai Anda sampai token kedaluwarsa atau Anda logout.

Pengguna dan workspace saat ini

GET /me mengembalikan pengguna, tipe akunnya, dan (untuk akun client) workspace-nya:

{
  "id": "…", "accountType": "client", "email": "anda@contoh.com", "displayName": "Ana",
  "activeTenantId": "…", "role": "owner",
  "memberships": [{ "tenantId": "…", "role": "owner", "tenant": { "id": "…", "name": "Ana's workspace", "slug": "ana-s-workspace-x1y2" } }]
}

Akun client memiliki tepat satu workspace (role bernilai owner). Workspace tidak punya anggota lain: kontributor memakai tipe akunnya sendiri dan tidak pernah bergabung ke workspace. Akun contributor mengembalikan activeTenantId: null, role: null, dan tanpa memberships.

Mini Program buatan kontributor masuk ke workspace lewat marketplace: GET /catalog/mini-programs menampilkan semua Mini Program yang sudah dipublikasikan beserta installation workspace ini, dan POST /mini-program-installations dengan { "miniProgramId": "…", "acceptedPermissions": [...] } memasangnya setelah semua izin yang diminta disetujui.