# @prisma/management-api-sdk

> TypeScript SDK for the Prisma Developer Platform Management API

Latest version **1.82.0** (published 2026-10-02) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @prisma/management-api-sdk
pnpm add @prisma/management-api-sdk
yarn add @prisma/management-api-sdk
bun add @prisma/management-api-sdk
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.82.0 |
| Published | 2026-10-02 |
| First published | 2025-12-05 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 831.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | prismabot, aqrln, tylerhogarth, ankur-datta-007 |
| Keywords | prisma, api, sdk, management, typescript |

## Links

- npm: https://www.npmjs.com/package/@prisma/management-api-sdk
- Repository: https://github.com/prisma/pdp-control-plane
- Homepage: https://github.com/prisma/pdp-control-plane#readme
- Issues: https://github.com/prisma/pdp-control-plane/issues
- npm.io page: https://npm.io/package/@prisma/management-api-sdk

## Dependencies (1)

- [openapi-fetch](https://npm.io/package/openapi-fetch.md) 0.14.0

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.82.0 (latest) — 2026-10-02
- 1.81.0 — 2026-10-02
- 1.80.0 — 2026-09-28
- 1.79.0 — 2026-09-25
- 1.78.0 — 2026-09-25
- 1.77.0 — 2026-09-25
- 1.76.0 — 2026-09-22
- 1.75.0 — 2026-09-21
- 1.74.0 — 2026-09-14
- 1.73.0 — 2026-09-11
- 1.72.0 — 2026-09-08
- 1.71.0 — 2026-08-31
- 1.70.0 — 2026-08-25
- 1.69.0 — 2026-08-25
- 1.68.0 — 2026-08-24
- … 73 more at https://npm.io/package/@prisma/management-api-sdk/versions

## README

# Management API SDK

A TypeScript SDK for the Prisma Developer Platform Management API. Use the simple client for direct API access, or the full SDK with built-in OAuth authentication and automatic token refresh.

Based on the [public OpenAPI 3.1 specification](https://api.prisma.io/v1/swagger-editor).

## Installation

```bash
npm install @prisma/management-api-sdk
```

## Basic Usage

For usage with an existing access or [service token](https://www.prisma.io/docs/postgres/introduction/management-api#service-tokens).

### Making API Calls

The client provides fully typed methods for all API endpoints:

```typescript
import { createManagementApiClient } from '@prisma/management-api-sdk'

const client = createManagementApiClient({
  token: 'your-access-token',
})

// List workspaces
const { data: workspaces, error } = await client.GET('/v1/workspaces')

// Get a specific project
const { data: project } = await client.GET('/v1/projects/{id}', {
  params: { path: { id: 'project-id' } },
})

// Create a new project
const { data: newProject } = await client.POST('/v1/workspaces/{workspaceId}/projects', {
  params: { path: { workspaceId: 'workspace-id' } },
  body: { name: 'My New Project' },
})

// Create a new database
const { data: newDatabase } = await client.POST('/v1/projects/{projectId}/databases', {
  params: { path: { projectId: 'project-id' } },
  body: {
    name: 'my-new-db-instance',
    region: 'us-east-1',
    isDefault: true,
  },
})

// Delete a database
const { error: deleteError } = await client.DELETE('/v1/databases/{databaseId}', {
  params: { path: { databaseId: 'database-id' } },
})
```

### Customizing the Client

You can override any `ClientOptions` from `openapi-fetch`, including `baseUrl`, `headers`, and other fetch options:

```typescript
import { createManagementApiClient } from '@prisma/management-api-sdk'

// Override baseUrl and add custom headers
const client = createManagementApiClient({
  token: 'your-access-token',
  baseUrl: 'https://api.example.com',
  headers: {
    'X-Custom-Header': 'value',
  },
})
```

**Note:** If you provide both `token` and `headers.Authorization`, the `headers.Authorization` takes precedence. The `baseUrl` defaults to `https://api.prisma.io` if not provided.

## Advanced Usage

For applications that need [OAuth authentication](https://www.prisma.io/docs/postgres/introduction/management-api#oauth-20-authentication), automatic token refresh, and token storage management, use the full SDK.

### OAuth Authentication Flow

The SDK uses OAuth 2.0 with PKCE for secure authentication. The flow is stateless - you're responsible for storing the `state` and `verifier` between the login URL generation and callback handling.

#### 1. Create the SDK Instance

```typescript
import { createManagementApiSdk, type TokenStorage } from '@prisma/management-api-sdk'

// Implement token storage for your environment
const tokenStorage: TokenStorage = {
  async getTokens() {
    const stored = localStorage.getItem('prisma-tokens')
    return stored ? JSON.parse(stored) : null
  },
  async setTokens(tokens) {
    localStorage.setItem('prisma-tokens', JSON.stringify(tokens))
  },
  async clearTokens() {
    localStorage.removeItem('prisma-tokens')
  },
}

// Create the SDK instance
const api = createManagementApiSdk({
  clientId: 'your-oauth-client-id',
  redirectUri: 'https://your-app.com/auth/callback',
  tokenStorage,
})
```

#### 2. Initiate Login

Generate the OAuth login URL. The returned `state` and `verifier` must be stored (e.g., in a session or cookie) for use when handling the callback:

```typescript
const { url, state, verifier } = await api.getLoginUrl({
  scope: 'workspace:admin offline_access',
  additionalParams: {
    utm_source: 'my-app',
    utm_medium: 'login',
  },
})

// Store state and verifier for the callback (e.g., in session storage)
sessionStorage.setItem('oauth-state', state)
sessionStorage.setItem('oauth-verifier', verifier)

// Redirect user to the login URL
window.location.href = url
```

#### 3. Handle the Callback

When the user is redirected back to your app, retrieve the stored `state` and `verifier` and pass them to `handleCallback`. On success, tokens are automatically stored via your `tokenStorage` implementation:

```typescript
// In your callback route handler
const callbackUrl = window.location.href

// Retrieve the stored values
const expectedState = sessionStorage.getItem('oauth-state')
const verifier = sessionStorage.getItem('oauth-verifier')

// Clean up stored values
sessionStorage.removeItem('oauth-state')
sessionStorage.removeItem('oauth-verifier')

try {
  await api.handleCallback({
    callbackUrl,
    verifier,
    expectedState,
  })
  // Tokens are now stored in tokenStorage and the client is ready to use
  console.log('Login successful!')
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Authentication failed:', error.message)
  }
}
```

#### 4. Make API Calls

The client automatically includes authentication headers and refreshes tokens when they expire:

```typescript
// List workspaces
const { data: workspaces } = await api.client.GET('/v1/workspaces')

// Get a specific project
const { data: project } = await api.client.GET('/v1/projects/{id}', {
  params: { path: { id: 'project-id' } },
})

// Create a new project
const { data: newProject } = await api.client.POST('/v1/workspaces/{workspaceId}/projects', {
  params: { path: { workspaceId: 'workspace-id' } },
  body: { name: 'My Project' },
})

// Create a new database
const { data: newDatabase } = await api.client.POST('/v1/projects/{projectId}/databases', {
  params: { path: { projectId: 'project-id' } },
  body: {
    name: 'production',
    region: 'us-east-1',
    isDefault: true,
  },
})

// Delete a database
const { error: deleteError } = await api.client.DELETE('/v1/databases/{databaseId}', {
  params: { path: { databaseId: 'database-id' } },
})
```

You can optionally cancel login URL generation:

```typescript
const controller = new AbortController()
const { url } = await api.getLoginUrl(
  { scope: 'workspace:admin offline_access' },
  { signal: controller.signal },
)
```

#### 5. Logout

```typescript
await api.logout() // Clears stored tokens
```

### Token Storage Interface

Implement this interface to handle token persistence in your environment:

```typescript
interface TokenStorage {
  /** Provide the stored tokens to the SDK */
  getTokens(): Promise<Tokens | null>
  /** Store new or updated tokens when the SDK has successfully authenticated or refreshed tokens */
  setTokens(tokens: Tokens): Promise<void>
  /** Clear the tokens when the user logs out or the refresh token is invalid */
  clearTokens(): Promise<void>
}

type Tokens = {
  /** The workspace ID that these tokens are valid for (extracted from the access token) */
  workspaceId: string
  /** The access token for API requests */
  accessToken: string
  /** The refresh token for obtaining new access tokens (only present if scope includes 'offline_access') */
  refreshToken?: string
}
```

#### Example: VS Code Extension

```typescript
const tokenStorage: TokenStorage = {
  async getTokens() {
    const workspaceId = await context.secrets.get('workspaceId')
    const accessToken = await context.secrets.get('accessToken')
    const refreshToken = await context.secrets.get('refreshToken')
    if (!workspaceId || !accessToken) return null
    return { workspaceId, accessToken, refreshToken: refreshToken || undefined }
  },
  async setTokens(tokens) {
    await context.secrets.store('workspaceId', tokens.workspaceId)
    await context.secrets.store('accessToken', tokens.accessToken)
    if (tokens.refreshToken) {
      await context.secrets.store('refreshToken', tokens.refreshToken)
    }
  },
  async clearTokens() {
    await context.secrets.delete('workspaceId')
    await context.secrets.delete('accessToken')
    await context.secrets.delete('refreshToken')
  },
}
```

#### Example: Node.js CLI

```typescript
import { readFile, writeFile, unlink } from 'node:fs/promises'
import { homedir } from 'node:os'
import { join } from 'node:path'

const tokenPath = join(homedir(), '.prisma', 'credentials.json')

const tokenStorage: TokenStorage = {
  async getTokens() {
    try {
      const data = await readFile(tokenPath, 'utf-8')
      return JSON.parse(data)
    } catch {
      return null
    }
  },
  async setTokens(tokens) {
    await writeFile(tokenPath, JSON.stringify(tokens, null, 2))
  },
  async clearTokens() {
    await unlink(tokenPath).catch(() => {})
  },
}
```

#### Example: Stateless Web Server

For stateless web servers (serverless, load-balanced), store the PKCE state in an encrypted cookie or database:

```typescript
// In your login route
app.get('/login', async (req, res) => {
  const { url, state, verifier } = await api.getLoginUrl({
    scope: 'workspace:admin offline_access',
  })

  // Store in encrypted cookie or database keyed by state
  res.cookie('oauth-verifier', verifier, { httpOnly: true, secure: true, signed: true })
  res.cookie('oauth-state', state, { httpOnly: true, secure: true, signed: true })

  res.redirect(url)
})

// In your callback route
app.get('/callback', async (req, res) => {
  const verifier = req.signedCookies['oauth-verifier']
  const expectedState = req.signedCookies['oauth-state']

  // Clear cookies
  res.clearCookie('oauth-verifier')
  res.clearCookie('oauth-state')

  await api.handleCallback({ callbackUrl: req.url, verifier, expectedState })
  // Tokens are now stored in tokenStorage
  // ... handle successful login
})
```

### Automatic Token Refresh

The SDK automatically handles token refresh when a refresh token is available (requires `offline_access` scope):

- When a request returns 401, the SDK refreshes the access token using the refresh token
- Concurrent requests during refresh are queued and resolved once refresh completes
- If refresh fails due to an invalid refresh token, tokens are cleared and `AuthError` is thrown with `refreshTokenInvalid: true`
- If no refresh token is available, an `AuthError` is thrown with the message "No refresh token available. Please log in again."

## API Reference

### `createManagementApiClient(options)`

Creates a raw API client without authentication handling. Useful if you want to manage authentication yourself or use a service token.

**Parameters:**

- `options.token?: string` - Access token (automatically converted to `Authorization: Bearer ${token}` header)
- `options.baseUrl?: string` - Base URL for API requests (defaults to `https://api.prisma.io`)
- `options.headers?: Record<string, string>` - Additional headers
- Other `ClientOptions` from `openapi-fetch` are also supported

**Returns:** A typed API client for making requests.

### `createManagementApiSdk(config)`

Creates a Management API SDK instance with OAuth authentication and automatic token refresh.

**Parameters:**

```typescript
type ManagementApiClientConfig = {
  // Required
  clientId: string // OAuth client ID
  redirectUri: string // OAuth redirect URI
  tokenStorage: TokenStorage

  // Optional (with defaults)
  apiBaseUrl?: string // Default: 'https://api.prisma.io'
  authBaseUrl?: string // Default: 'https://auth.prisma.io'
}
```

**Returns:** An object with:

- `client` - The typed API client for making requests
- `getLoginUrl(options, asyncOptions?)` - Generate OAuth login URL with specified scope (`asyncOptions.signal` supported)
- `handleCallback(options, asyncOptions?)` - Handle OAuth callback and store tokens via `tokenStorage`
- `logout(asyncOptions?)` - Clear stored tokens

### Cancellation behavior

- You can optionally pass `signal` to any async SDK function:
  - `client.GET/POST/...` via request options (`{ signal }`)
  - `getLoginUrl`, `handleCallback`, and `logout` via `asyncOptions` (`{ signal }`)

## Error Handling

The SDK exports two error classes:

### `AuthError`

Thrown for authentication-related errors:

- OAuth callback errors (includes `error_description` when available)
- Invalid or missing tokens
- Token refresh failures

```typescript
import { AuthError } from '@prisma/management-api-sdk'

try {
  await api.handleCallback({ callbackUrl, verifier, expectedState })
} catch (error) {
  if (error instanceof AuthError) {
    if (error.refreshTokenInvalid) {
      // Token is invalid/expired, user needs to log in again
      const { url } = await api.getLoginUrl({ scope: 'workspace:admin offline_access' })
      // redirect to url...
    } else {
      // Other auth errors (e.g., "access_denied: User cancelled")
      console.error('Auth error:', error.message)
    }
  }
}
```

### `FetchError`

Thrown for network-related errors. Includes the original error as `cause` for debugging:

```typescript
import { FetchError } from '@prisma/management-api-sdk'

try {
  const { data } = await client.GET('/v1/workspaces')
} catch (error) {
  if (error instanceof FetchError) {
    console.error('Network error:', error.message)
    console.error('Cause:', error.cause) // Original error for debugging
  }
}
```

## TypeScript Types

The SDK exports all API types generated from the OpenAPI spec:

```typescript
import type { paths, components } from '@prisma/management-api-sdk'

// Access response types
type Workspace = components['schemas']['Workspace']
type Project = components['schemas']['Project']
```

## Regenerating API Types

The API types are generated from the OpenAPI spec:

```bash
pnpm generate-api-client
```

This fetches the latest spec from `https://api.prisma.io/v1/doc` and generates `src/api.d.ts`.

---
_Source: https://npm.io/package/@prisma/management-api-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._