管理 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 .

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:

• Prisma 管理 API 入门

  ¥Getting started with the Prisma Management API

• 使用 GitHub 配置预览数据库操作和 Prisma Postgres

  ¥Provisioning preview databases with GitHub Actions and Prisma Postgres

• 合作伙伴数据库配置和用户申领流程

  ¥Partner database provisioning & user claim flow

基本 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

The Prisma Postgres API supports two authentication methods:

• Service tokens — for accessing resources in your own workspace

• 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.

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

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 authentication

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

To obtain a client ID and client secret:

1. 打开 。

   ¥Open the .

2. Click the 🧩 Integrations tab.

3. Under Published Applications, click New Application.

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

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

OAuth authorization flow

To use OAuth 2.0, your application must:

1. 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. 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. 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"

注意

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.

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

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

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

   • 客户端 ID/密钥：From your OAuth app

     ¥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"
  }

• 响应：

  ¥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

连接字符串

¥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