---
title: "TypeScript SDK installation"
description: "Install the PgBeam SDK, configure the client, authenticate, and learn the two access patterns."
canonical: "https://pgbeam.com/docs/ts-sdk"
last-updated: "2026-10-29T19:01:20.000Z"
---

# TypeScript SDK installation

> Install the PgBeam SDK, configure the client, authenticate, and learn the two access patterns.

URL: https://pgbeam.com/docs/ts-sdk

## Installation

```bash
npm install pgbeam
```

## Client setup

```typescript
import { PgBeamClient } from "pgbeam";

const client = new PgBeamClient({
  token: "pbu_...",
  baseUrl: "https://api.pgbeam.com",
});

const { api } = client;
```

## Constructor options

| Option       | Type                                              | Description                                             |
| ------------ | ------------------------------------------------- | ------------------------------------------------------- |
| `token`      | `string \| null \| () => Promise<string \| null>` | JWT token, API key, or async function that resolves one |
| `baseUrl`    | `string`                                          | Base URL of the PgBeam API                              |
| `fetch`      | `typeof globalThis.fetch`                         | Optional custom fetch implementation                    |
| `onResponse` | `OnResponseHook`                                  | Optional hook called after every response               |

## Authentication

The `token` constructor option accepts a static string, an async function, or an API key. Choose the approach that fits your environment.

**Static token**

```typescript
const client = new PgBeamClient({
  token: "your-session-token",
  baseUrl: "https://api.pgbeam.com",
});
```

**Async token**

```typescript
const client = new PgBeamClient({
  token: async () => {
    // Refresh or fetch token dynamically
    return await getToken();
  },
  baseUrl: "https://api.pgbeam.com",
});
```

**API key**

```typescript
const client = new PgBeamClient({
  token: "pbu_your_api_key",
  baseUrl: "https://api.pgbeam.com",
});
```

See [API Keys](/docs/api-keys) for key creation and rotation.

## Usage patterns

The SDK supports two styles for making requests: tag-based access and route-based access. Both are fully type-safe.

### Tag-based access

Methods are grouped by tag: `projects`, `databases`, `analytics`, `platform`, and `account`.

```typescript
// List all projects
const projects = await api.projects.listProjects({
  queryParams: { org_id: "org_xxx" },
});

// Get a single database
const db = await api.databases.getDatabase({
  pathParams: { project_id: "prj_xxx", database_id: "db_xxx" },
});
```

### Route-based access

Use `api.request()` with a route string for a more REST-like style:

```typescript
const projects = await api.request("GET /v1/projects", {
  queryParams: { org_id: "org_xxx" },
});

const project = await api.request("GET /v1/projects/{project_id}", {
  pathParams: { project_id: "prj_xxx" },
});
```

> **Which style should I use?**
>
> Tag-based access is recommended for most use cases. It provides better
> discoverability through IDE autocomplete. Route-based access is useful when
> you want your code to mirror the REST endpoints directly.