Skip to main content

管理 API

概述​

¥Overview

本页介绍 Prisma Management API，它使你能够以编程方式在 中管理 platform 资源（例如项目或 Prisma Postgres 实例）。

¥This page covers the Prisma Management API which enables you to programmatically manage platform resources (e.g. projects or Prisma Postgres instances) in .

TypeScript SDK

@prisma/management-api-sdk 提供了一个类型化的 TypeScript 客户端，内置 OAuth 身份验证和自动令牌刷新功能。这是在 TypeScript/JavaScript 应用中与管理 API 交互的推荐方式。

¥The @prisma/management-api-sdk provides a typed TypeScript client with built-in OAuth authentication and automatic token refresh. It's the recommended way to interact with the Management API in TypeScript/JavaScript applications.

OpenAPI

交互式 OpenAPI 3.1 规范可在此处获取，你可以在其中探索端点、请求/响应主体以及详细示例。

¥An interactive OpenAPI 3.1 specification is available here, where you can explore endpoints, request/response bodies, and detailed examples.

指南

我们有三个指南可帮助你在常见场景中使用 Management API：

¥We have three guides to help you use the Management API for common scenarios:

基本 URL​

¥Base URL

Prisma Postgres API 请求的基本 URL 为：

¥The base URL for a Prisma Postgres API request is:

https://api.prisma.io/v1

将端点路径附加到基本 URL 以构建请求的完整 URL。例如：

¥Append an endpoint path to the base URL to construct the full URL for a request. For example:

https://api.prisma.io/v1/projects/{projectId}

身份验证​

¥Authentication

Prisma Postgres API 支持两种身份验证方法：

¥The Prisma Postgres API supports two authentication methods:

  • 服务令牌 — 用于访问你自己工作区中的资源

    ¥Service tokens — for accessing resources in your own workspace

  • OAuth 2.0 访问令牌 — 用于代表用户访问或管理资源

    ¥OAuth 2.0 access tokens — for accessing or managing resources on behalf of users

服务令牌​

¥Service tokens

服务令牌在你的 工作区中手动创建。它们非常适合服务器到服务器的集成或在你自己的工作区中配置数据库。

¥Service tokens are manually created in your workspace. They're ideal for server-to-server integrations or provisioning databases in your own workspace.

要使用服务令牌进行身份验证，请将其包含在 Authorization 标头中：

¥To authenticate with a service token, include it in the Authorization header:

Authorization: Bearer $TOKEN

创建服务令牌​

¥Creating a service token

  1. 打开 。

    ¥Open the .

  2. 导航到你的工作区。

    ¥Navigate to your workspace.

  3. 转到工作区的“设置”页面，然后选择“服务令牌”。

    ¥Go to the Settings page of your workspace and select Service Tokens.

  4. 点击“新建服务令牌”，复制生成的令牌以备将来使用。

    ¥Click New Service Token and copy the generated token for future use.

OAuth 2.0 身份验证​

¥OAuth 2.0 authentication

如果你想代表用户执行操作，并直接在其工作区中创建或管理数据库，请使用 OAuth 2.0。

¥Use OAuth 2.0 if you want to act on behalf of users and create or manage databases directly in their workspaces.

创建 OAuth 凭据​

¥Creating OAuth credentials

要获取客户端 ID 和客户端密钥：

¥To obtain a client ID and client secret:

  1. 打开 。

    ¥Open the .

  2. 点击“集成”选项卡。

    ¥Click the 🧩 Integrations tab.

  3. 在“已发布应用”下，点击“新建应用”。

    ¥Under Published Applications, click New Application.

  4. 输入名称、描述和重定向 URI（用户授权后将被重定向到的 URL）。

    ¥Enter a Name, Description, and Redirect URI (the URL where users will be redirected after authorization).

  5. 点击“继续”，然后将你的客户端 ID 和客户端密钥复制并保存到安全位置。

    ¥Click Continue, then copy and store your Client ID and Client Secret to a secure location.

OAuth 授权流程​

¥OAuth authorization flow

要使用 OAuth 2.0，你的应用必须：

¥To use OAuth 2.0, your application must:

  1. 使用你的客户端 ID 和重定向 URI 将用户重定向到授权 URL：

    ¥Redirect users to the authorization URL with your client ID and redirect URI:

    https://auth.prisma.io/authorize?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&response_type=code&scope=workspace:admin

  2. 接收授权码：用户授权你的应用后，将被重定向到你的重定向 URI，并带有 code 参数：

    ¥Receive the authorization code: After the user authorizes your application, they'll be redirected to your redirect URI with a code parameter:

    https://your-app.com/callback?code=abc123...

  3. 将代码交换为访问令牌：在以下请求中使用步骤 2 中的代码

    ¥Exchange the code for an access token: Use the code from step 2 in the following request

curl -X POST https://auth.prisma.io/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "code=$CODE" \
  -d "grant_type=authorization_code" \
  -d "redirect_uri=$REDIRECT_URI"
注意

$CODE 是上述步骤 2 中收到的授权码。$REDIRECT_URI 必须与你创建 OAuth 凭据时配置的内容完全一致。

¥The $CODE is the authorization code received in step 2 above. The $REDIRECT_URI must match exactly what you configured when creating your OAuth credentials.

从响应中获取访问令牌后，将其包含在对管理 API 的请求中：

¥Once you have an access token from the response, include it in requests to the Management API:

curl --location "https://api.prisma.io/v1/projects" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "my_project",
    "region": "us-east-1"
  }'

说明​

¥Instructions

Authentication in Postman

使用服务令牌​

¥Using a Service token

  1. 创建新请求。

    ¥Create a new request.

  2. 转到“授权”选项卡。

    ¥Go to the Authorization tab.

  3. 将类型设置为 Bearer Token。

    ¥Set type to Bearer Token.

  4. 粘贴你的服务令牌。

    ¥Paste your service token.

使用 OAuth 2​

¥Using OAuth 2

  1. 在“授权”选项卡中，将类型设置为 OAuth 2.0。

    ¥In the Authorization tab, set type to OAuth 2.0.

  2. 点击“获取新的访问令牌”并填写详细信息：

    ¥Click Get New Access Token and fill in the details:

    • 令牌名称：任意名称

      ¥Token Name: Any name

    • 授权类型：授权码

      ¥Grant Type: Authorization Code

    • 重定向 URI：你的应用重定向 URI（必须与你在 OAuth 凭据中配置的 URI 匹配）

      ¥Redirect URI: Your app's redirect URI (must match what you configured in OAuth credentials)

    • 身份验证 URL：https://auth.prisma.io/authorize

      ¥Auth URL: https://auth.prisma.io/authorize

    • 客户端 ID/密钥：从你的 OAuth 应用

      ¥Client ID / Secret: From your OAuth app

    • 范围：workspace:admin offline_access（根据需要）

      ¥Scope: workspace:admin offline_access (as needed)

  3. 完成流程并在请求中使用令牌。

    ¥Complete the flow and use the token in your requests.

Authentication in SwaggerUI

使用服务令牌​

¥Using a Service token

  1. 点击“授权”。

    ¥Click Authorize.

  2. 将服务令牌粘贴到相关输入中。

    ¥Paste the service token into the relevant input.

  3. 再次点击“授权”。

    ¥Click Authorize again.

Swagger 规范通过 Authorization 标头支持 Bearer 令牌。

¥The Swagger spec supports a Bearer token via the Authorization header.

使用 OAuth 2​

¥Using OAuth 2

  1. 点击“授权”。

    ¥Click Authorize.

  2. 选择 OAuth2 流程。

    ¥Choose the OAuth2 flow.

  3. 请提供你的 clientId、clientSecret 和重定向 URI。

    ¥Provide your clientId, clientSecret, and redirect URI.

  4. 完成授权流程以获取访问权限。

    ¥Complete the authorization flow to acquire access.

端点​

¥Endpoints

工作区​

¥Workspaces

GET /workspaces​

检索当前用户可访问的工作区信息。

¥Retrieve information about the workspaces accessible by the current user.

  • 查询参数：

    ¥Query parameters:

    • cursor（可选）：分页光标

      ¥cursor (optional): Cursor for pagination

    • limit（可选，默认值：100）：结果数量限制

      ¥limit (optional, default: 100): Limit number of results

  • 响应：

    ¥Responses:

    • 200 OK：工作区列表

      ¥200 OK: List of workspaces

    • 401 Unauthorized：身份验证令牌无效或缺失

      ¥401 Unauthorized: Invalid or missing authentication token

项目​

¥Projects

GET /projects​

检索所有项目。

¥Retrieve all projects.

  • 查询参数：

    ¥Query parameters:

    • cursor（可选）：分页光标

      ¥cursor (optional): Cursor for pagination

    • limit（可选，默认值：100）：结果数量限制

      ¥limit (optional, default: 100): Limit number of results

  • 响应：

    ¥Responses:

    • 200 OK：项目列表

      ¥200 OK: List of projects

    • 401 Unauthorized

POST /projects​

创建新项目。

¥Create a new project.

  • 请求正文：

    ¥Request body:

    {
      "region": "us-east-1",
      "name": "My Project"
    }

  • 响应正文：

    ¥Response body:

    {
      "data": {
        "id": "proj_abc123",
        "type": "project",
        "name": "My Project",
        "createdAt": "2025-12-14T21:42:30.545Z",
        "workspace": {
          "id": "wksp_xyz789",
          "name": "My Workspace"
        },
        "database": {
          "id": "db_def456",
          "type": "database",
          "name": "My Project",
          "createdAt": "2025-12-14T21:42:30.545Z",
          "region": {
            "id": "us-east-1",
            "name": "US East (N. Virginia)"
          },
          "status": "ready",
          "connectionString": "prisma+postgres://accelerate.prisma-data.net/?api_key=...",
          "directConnection": {
            "host": "db.prisma.io:5432",
            "user": "your_user_id",
            "pass": "your_password"
          },
          "isDefault": true
        }
      }
    }

    响应包含一个 directConnection 对象，其中包含用于直接连接到底层 PostgreSQL 数据库的凭据。使用以下值构建你的 DATABASE_URL：

    ¥The response includes a directConnection object with credentials for connecting directly to the underlying PostgreSQL database. Use these values to build your DATABASE_URL:

    postgresql://{user}:{pass}@{host}/postgres?sslmode=require

    例如，对于上述响应：

    ¥For example, given the response above:

    postgresql://your_user_id:your_password@db.prisma.io:5432/postgres?sslmode=require

    在 .env 文件中将以下内容设置为 DATABASE_URL 环境变量：

    ¥Set this as your DATABASE_URL environment variable in your .env file:

    DATABASE_URL="postgresql://your_user_id:your_password@db.prisma.io:5432/postgres?sslmode=require"

    此直接连接字符串是连接到 Prisma Postgres 数据库的推荐方式，适用于所有用例，包括 Prisma Client、迁移和直接数据库访问。

    ¥This direct connection string is the recommended way to connect to your Prisma Postgres database for all use cases including Prisma Client, migrations, and direct database access.

  • 响应：

    ¥Responses:

    • 201 Created：项目已创建

      ¥201 Created: Project created

    • 401 Unauthorized

GET /projects/{id}​

通过 ID 检索特定项目。

¥Retrieve a specific project by ID.

  • 路径参数：

    ¥Path parameters:

    • id：项目 ID

      ¥id: Project ID

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

    • 404 Not Found

DELETE /projects/{id}​

删除项目。

¥Deletes a project.

  • 路径参数：

    ¥Path parameters:

    • id：项目 ID

      ¥id: Project ID

  • 响应：

    ¥Responses:

    • 204 No Content

    • 400 Bad Request：依赖阻止删除

      ¥400 Bad Request: Dependencies prevent deletion

    • 401 Unauthorized

    • 404 Not Found

POST /projects/{id}/transfer​

将项目转移给新的工作区所有者。

¥Transfer a project to a new workspace owner.

  • 路径参数：

    ¥Path parameters:

    • id：项目 ID

      ¥id: Project ID

  • 请求正文：

    ¥Request body:

    {
      "recipientAccessToken": "string"
    }

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

    • 404 Not Found

数据库​

¥Databases

GET /projects/{projectId}/databases​

检索项目的所有数据库。

¥Retrieve all databases for a project.

  • 路径参数：

    ¥Path parameters:

    • projectId：项目 ID

      ¥projectId: Project ID

  • 查询参数：

    ¥Query parameters:

    • cursor（可选）：分页光标

      ¥cursor (optional): Cursor for pagination

    • limit（可选，默认值：100）：结果数量限制

      ¥limit (optional, default: 100): Limit number of results

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

    • 404 Not Found

POST /projects/{projectId}/databases​

创建新数据库。

¥Create a new database.

  • 路径参数：

    ¥Path parameters:

    • projectId：项目 ID

      ¥projectId: Project ID

  • 请求正文：

    ¥Request body:

    {
      "region": "us-east-1",
      "name": "My Database",
      "isDefault": false,
      "fromDatabase": { 
        "id": "databaseId", 
        "backupId": "string"
      }
    }
    note

    fromDatabase only when creating the database from an existing one or a backup. :::使用

  • 响应：

    ¥Responses:

    • 201 Created

    • 400 Default database already exists

    • 401 Unauthorized

    • 403 Forbidden

GET /databases/{databaseId}​

检索特定数据库。

¥Retrieve a specific database.

  • 路径参数：

    ¥Path parameters:

    • databaseId：数据库 ID

      ¥databaseId: Database ID

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

    • 404 Not Found

DELETE /databases/{databaseId}​

删除数据库。

¥Delete a database.

  • 路径参数：

    ¥Path parameters:

    • databaseId：数据库 ID

      ¥databaseId: Database ID

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

    • 403 Cannot delete default environment

    • 404 Not Found

GET /databases/{databaseId}/usage​

获取数据库的使用情况指标。

¥Get usage metrics for a database.

  • 路径参数：

    ¥Path parameters:

    • databaseId：数据库 ID

      ¥databaseId: Database ID

  • 查询参数：

    ¥Query parameters:

    • startDate（可选）：使用期的起始日期

      ¥startDate (optional): Start date for the usage period

    • endDate（可选）：使用期限结束日期

      ¥endDate (optional): End date for the usage period

  • 响应正文：

    ¥Response body:

    {
      "period": {
        "start": "2025-12-01T00:00:00.000Z",
        "end": "2025-12-14T21:39:23.331Z"
      },
      "metrics": {
        "operations": {
          "used": 0,
          "unit": "ops"
        },
        "storage": {
          "used": 0,
          "unit": "GiB"
        }
      },
      "generatedAt": "2025-12-14T21:39:23.331Z"
    }

  • 响应：

    ¥Responses:

    • 200 OK：返回使用情况指标

      ¥200 OK: Usage metrics returned

    • 400 Bad Request：无效请求参数

      ¥400 Bad Request: Invalid request parameters

    • 401 Unauthorized

    • 404 Not Found

    • 500 Internal Server Error：获取指标时出错

      ¥500 Internal Server Error: Error occurred while fetching metrics

连接字符串​

¥Connection strings

GET /databases/{databaseId}/connections​

检索所有数据库连接字符串。

¥Retrieve all database connection strings.

  • 路径参数：

    ¥Path parameters:

    • databaseId：数据库 ID

      ¥databaseId: Database ID

  • 查询参数：

    ¥Query parameters:

    • cursor（可选）：分页光标

      ¥cursor (optional): Cursor for pagination

    • limit（可选，默认值：100）：结果数量限制

      ¥limit (optional, default: 100): Limit number of results

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

POST /databases/{databaseId}/connections​

创建一个新的连接字符串。

¥Create a new connection string.

  • 路径参数：

    ¥Path parameters:

    • databaseId：数据库 ID

      ¥databaseId: Database ID

  • 请求正文：

    ¥Request body:

    {
      "name": "Connection Name"
    }

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

    • 404 Not Found

DELETE /connections/{id}​

删除连接字符串。

¥Delete a connection string.

  • 路径参数：

    ¥Path parameters:

    • id：连接 ID

      ¥id: Connection ID

  • 响应：

    ¥Responses:

    • 204 No Content

    • 401 Unauthorized

    • 404 Not Found

备份​

¥Backups

GET /databases/{databaseId}/backups​

检索数据库备份。

¥Retrieve database backups.

  • 路径参数：

    ¥Path parameters:

    • databaseId：数据库 ID

      ¥databaseId: Database ID

  • 查询参数：

    ¥Query parameters:

    • limit（可选，默认值：25）：结果数量限制

      ¥limit (optional, default: 25): Limit number of results

  • 响应：

    ¥Responses:

    • 200 OK

    • 401 Unauthorized

    • 404 Not Found

集成​

¥Integrations

GET /workspaces/{workspaceId}/integrations​

检索给定工作区的集成。

¥Retrieve integrations for the given workspace.

  • 路径参数：

    ¥Path parameters:

    • workspaceId：工作区 ID

      ¥workspaceId: Workspace ID

  • 查询参数：

    ¥Query parameters:

    • cursor（可选）：分页光标

      ¥cursor (optional): Cursor for pagination

    • limit（可选，默认值：100）：结果数量限制

      ¥limit (optional, default: 100): Limit number of results

  • 响应：

    ¥Responses:

    • 200 OK：集成详情列表：

      ¥200 OK: List of integrations with details:

      • id：集成 ID

        ¥id: Integration ID

      • createdAt：创建时间戳

        ¥createdAt: Creation timestamp

      • scopes：授权范围数组

        ¥scopes: Array of granted scopes

      • client：包含 id、name、createdAt 的对象

        ¥client: Object containing id, name, createdAt

      • createdByUser：包含 id、email、displayName 的对象

        ¥createdByUser: Object containing id, email, displayName

    • 401 Unauthorized：缺少或无效的身份验证令牌

      ¥401 Unauthorized: Missing or invalid authentication token

    • 404 Not Found：未找到工作区

      ¥404 Not Found: Workspace not found

DELETE /workspaces/{workspaceId}/integrations/{clientId}​

撤销指定客户端 ID 的集成令牌。

¥Revokes the integration tokens with the given client ID.

  • 路径参数：

    ¥Path parameters:

    • workspaceId：工作区 ID（例如 wksp_1234）

      ¥workspaceId: Workspace ID (e.g. wksp_1234)

    • clientId：集成客户端 ID（例如 itgr_5678）

      ¥clientId: Integration client ID (e.g. itgr_5678)

  • 响应：

    ¥Responses:

    • 204 No Content：集成令牌已成功撤销

      ¥204 No Content: Integration tokens revoked successfully

    • 401 Unauthorized：缺少或无效的身份验证令牌

      ¥401 Unauthorized: Missing or invalid authentication token

    • 404 Not Found：未找到工作区或集成

      ¥404 Not Found: Workspace or integration not found

杂项​

¥Misc

GET /regions/postgres​

检索所有可用区域。

¥Retrieve all available regions.

  • 响应：

    ¥Responses:

    • 200 OK：返回可用/不支持的区域列表

      ¥200 OK: Returns list of available/unsupported regions

    • 401 Unauthorized