> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For full documentation content, see https://developers.alephant.io/llms-full.txt.

# SDKs & Integrations

> Official Alephant API client libraries for TypeScript and Python

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

| API           | Language             | Package                                |
| ------------- | -------------------- | -------------------------------------- |
| SaaS API      | TypeScript / Node.js | `@alephantai/saas-api`                 |
| SaaS API      | Python               | `alephantai-saas-api`                  |
| Analytics API | TypeScript / Node.js | `@alephantai/logs-collector-analytics` |
| Analytics API | Python               | `alephantai-analytics-api`             |

## 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:

```typescript
import { AlephantSaaSClient } from "@alephantai/saas-api";

const client = new AlephantSaaSClient({
  baseUrl: process.env.ALEPHANT_SAAS_BASE_URL!,
  apiKey: `Bearer ${process.env.ALEPHANT_VIRTUAL_KEY}`,
});

const { data } = await client.cockpit.cockpitScope();

const workspaceId = data.workspace?.id;
const agentOrMemberId = data.entity?.id;
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](/sdk-reference/saa-s-sdk/type-script-sdk) and [Python](/sdk-reference/saa-s-sdk/python-sdk) guides.

## Available SDKs

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

* [**TypeScript / Node.js**](/sdk-reference/saa-s-sdk/type-script-sdk): Available on npm as `@alephantai/saas-api`. Ideal for Next.js, Express, or backend Node.js services.
* [**Python**](/sdk-reference/saa-s-sdk/python-sdk): 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.