SDKs & Integrations

Alephant provides official, strongly-typed client libraries to help you interact with our APIs. The SDKs are generated from our OpenAPI specification using Fern and published separately for the SaaS API and Analytics API.

By using our SDKs, you benefit from:

• Type Safety: Full autocomplete and compilation-time checks in your IDE.
• Convenience: Built-in error handling, pagination, and retry logic.
• Async Support: Native support for Promises in JS/TS and async/await in Python.

Published SDKs

Cockpit scope: bootstrap from a virtual key

Many integrations only receive a virtual key (vk-…)—for example an agent or member key—not a user JWT and not X-Workspace-Id. Before calling workspace-scoped SaaS APIs or analytics that require IDs, use GET /api/v1/cockpit/scope.

Authentication: send Authorization: Bearer <full virtual key token> (same header shape as the OpenAPI Authorization parameter on Cockpit routes). No X-Workspace-Id header is required for this endpoint.

What you get back (when the key is valid and not degraded):

• workspace: id (workspace UUID) and name.
• virtual_key: metadata for the authenticated key (id, label, prefix, limits, etc.).
• entity (optional): present when the key is bound to an agent or member—type, id, name, optional department (display name), and department_id (department UUID, or JSON null if unassigned).

If the key is not bound to an entity, entity may be omitted; you still get workspace and virtual_key. Use workspace.id as X-Workspace-Id for PAT/JWT calls, and entity.id / entity.department_id when downstream APIs need agent or department scope.

TypeScript (generated client): configure the client as usual, then call the Cockpit resource with the VK in the request headers:

1
import { AlephantSaaSClient } from "@alephantai/saas-api";
2
3
const client = new AlephantSaaSClient({
4
  baseUrl: process.env.ALEPHANT_SAAS_BASE_URL!,
5
  apiKey: `Bearer ${process.env.ALEPHANT_VIRTUAL_KEY}`,
6
});
7
8
const { data } = await client.cockpit.cockpitScope();
9
10
const workspaceId = data.workspace?.id;
11
const agentOrMemberId = data.entity?.id;
12
const departmentId = data.entity?.department_id ?? null;

The Python SDK exposes the same route under its generated Cockpit client; pass the Authorization header with Bearer vk-… in the same way. Language-specific patterns are covered in the TypeScript and Python guides.

Available SDKs

Currently, we maintain official SaaS SDKs for the following languages:

• TypeScript / Node.js: Available on npm as @alephantai/saas-api. Ideal for Next.js, Express, or backend Node.js services.
• Python: Available on PyPI as alephantai-saas-api. Ideal for Django, FastAPI, data science pipelines, or automation scripts.

Select a language from the sidebar to view installation instructions and usage examples.