Skip to main content
Prisma Documentation Docs

Search documentation

Type to search this documentation.

On this pageOverview

SDK

Overview

Section titled “Overview”

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

Section titled “Installation”
title="bun"
bun add @prisma/management-api-sdk
pnpm
pnpm add @prisma/management-api-sdk
yarn
yarn add @prisma/management-api-sdk
npm
npm install @prisma/management-api-sdk

Basic usage

Section titled “Basic usage”

For usage with an existing access or service token.

Making API calls

Section titled “Making API calls”

The client provides fully typed methods for all API endpoints:

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

Section titled “Customizing the client”

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

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",

  },

});

Advanced usage

Section titled “Advanced usage”

For applications that need OAuth authentication, automatic token refresh, and token storage management, use the full SDK.

OAuth authentication flow

Section titled “OAuth authentication flow”

The SDK uses OAuth 2.0 with PKCE. The flow is stateless, so you are responsible for storing the state and verifier between generating the login URL and handling the callback.

1. Create the SDK instance

Section titled “1. Create the SDK instance”
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

Section titled “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:

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

Section titled “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:

// 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

Section titled “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

Section titled “5. Logout”
await api.logout(); // Clears stored tokens

Token storage interface

Section titled “Token storage interface”

Implement this interface to handle token persistence in your environment:

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

Section titled “Example: VS Code Extension”
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

Section titled “Example: Node.js CLI”
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

Section titled “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

Section titled “API reference”

createManagementApiClient(options)

Section titled “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)

Section titled “createManagementApiSdk(config)”

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

Parameters:

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

Section titled “Error handling”

The SDK exports two error classes:

AuthError

Section titled “AuthError”

Thrown for authentication-related errors:

  • OAuth callback errors (includes error_description when available)
  • Invalid or missing tokens
  • Token refresh failures
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

Section titled “FetchError”

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

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

Section titled “TypeScript types”

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

import type { paths, components } from "@prisma/management-api-sdk";

// Access response types

type Workspace = components["schemas"]["Workspace"];

type Project = components["schemas"]["Project"];
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu