SDK - Prisma — ContextQMD

Overview

The @prisma/management-api-sdk is a TypeScript SDK for the Prisma Data 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.

Installation

npm

npm install @prisma/management-api-sdk

Basic usage

For usage with an existing access or service token.

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, 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. Use api.client with the same methods shown in Basic usage.

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(() => {});
  },
};

For other environments:

VS Code extensions - Use context.secrets for secure storage
Stateless web servers - Store PKCE state/verifier in encrypted cookies or a database

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) - Generate OAuth login URL with specified scope
handleCallback(options) - Handle OAuth callback and store tokens via tokenStorage
logout() - Clear stored tokens

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"];