ContextQMD
Back to Prisma

Management API

apps/docs/content/docs.v6/postgres/introduction/management-api.mdx

latest13.0 KB
Original Source

Overview

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

:::tip[TypeScript SDK] 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. :::

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

:::tip[Guides] We have three guides to help you use the Management API for common scenarios:

Base URL

The base URL for a Prisma Postgres API request is:

https://api.prisma.io/v1

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 Prisma Console 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 Prisma Console.
  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.

Creating OAuth credentials

To obtain a client ID and client secret:

  1. Open the Prisma Console.
  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

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

:::note 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:

bash
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

<details> <summary>Authentication in Postman</summary>

Using a Service token

  1. Create a new request.
  2. Go to the Authorization tab.
  3. Set type to Bearer Token.
  4. Paste your service token.

Using OAuth 2

  1. 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
    • Client ID / Secret: From your OAuth app
    • Scope: workspace:admin offline_access (as needed)
  3. Complete the flow and use the token in your requests.
</details> <details> <summary>Authentication in SwaggerUI</summary>

Using a Service token

  1. Click Authorize.
  2. Paste the service token into the relevant input.
  3. Click Authorize again.

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

Using OAuth 2

  1. Click Authorize.
  2. Choose the OAuth2 flow.
  3. Provide your clientId, clientSecret, and redirect URI.
  4. Complete the authorization flow to acquire access.
</details>

Endpoints

Workspaces

GET /workspaces

Retrieve information about the workspaces accessible by the current user.

  • Query parameters:
    • cursor (optional): Cursor for pagination
    • limit (optional, default: 100): Limit number of results
  • Responses:
    • 200 OK: List of workspaces
    • 401 Unauthorized: Invalid or missing authentication token

Projects

GET /projects

Retrieve all projects.

  • Query parameters:
    • cursor (optional): Cursor for pagination
    • limit (optional, default: 100): Limit number of results
  • Responses:
    • 200 OK: List of projects
    • 401 Unauthorized

POST /projects

Create a new project.

  • Request body:

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

  • Response body:

    json
    {
  "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
    }
  }
}

    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:[email protected]:5432/postgres?sslmode=require

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

    text
    DATABASE_URL="postgresql://your_user_id:[email protected]:5432/postgres?sslmode=require"

    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: Project created
    • 401 Unauthorized

GET /projects/{id}

Retrieve a specific project by ID.

  • Path parameters:
    • id: Project ID
  • Responses:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /projects/{id}

Deletes a project.

  • Path parameters:
    • id: Project ID
  • Responses:
    • 204 No Content
    • 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: Project ID
  • Request body:
    json
    {
  "recipientAccessToken": "string"
}
  • Responses:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

Databases

GET /projects/{projectId}/databases

Retrieve all databases for a project.

  • Path parameters:
    • projectId: Project ID
  • Query parameters:
    • cursor (optional): Cursor for pagination
    • 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: Project ID
  • Request body:
    json
    {
  "region": "us-east-1",
  "name": "My Database",
  "isDefault": false,
  "fromDatabase": {
    "id": "databaseId",
    "backupId": "string"
  }
}
    :::note Use 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: Database ID
  • Responses:
    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /databases/{databaseId}

Delete a database.

  • Path parameters:
    • 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: Database ID
  • Query parameters:
    • startDate (optional): Start date for the usage period
    • endDate (optional): End date for the usage period
  • Response body:
    json
    {
  "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: Usage metrics returned
    • 400 Bad Request: Invalid request parameters
    • 401 Unauthorized
    • 404 Not Found
    • 500 Internal Server Error: Error occurred while fetching metrics

Connection strings

GET /databases/{databaseId}/connections

Retrieve all database connection strings.

  • Path parameters:
    • databaseId: Database ID
  • Query parameters:
    • cursor (optional): Cursor for pagination
    • 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: Database ID

  • Request body:

    json
    {
  "name": "Connection Name"
}

  • Responses:

    • 200 OK
    • 401 Unauthorized
    • 404 Not Found

DELETE /connections/{id}

Delete a connection string.

  • Path parameters:
    • id: Connection ID
  • Responses:
    • 204 No Content
    • 401 Unauthorized
    • 404 Not Found

Backups

GET /databases/{databaseId}/backups

Retrieve database backups.

  • Path parameters:
    • databaseId: Database ID
  • Query parameters:
    • 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: Workspace ID
  • Query parameters:
    • cursor (optional): Cursor for pagination
    • limit (optional, default: 100): Limit number of results
  • Responses:
    • 200 OK: List of integrations with details:
      • id: Integration ID
      • createdAt: Creation timestamp
      • scopes: Array of granted scopes
      • client: Object containing id, name, createdAt
      • createdByUser: Object containing id, email, displayName
    • 401 Unauthorized: Missing or invalid authentication token
    • 404 Not Found: Workspace not found

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

Revokes the integration tokens with the given client ID.

  • Path parameters:
    • workspaceId: Workspace ID (e.g. wksp_1234)
    • clientId: Integration client ID (e.g. itgr_5678)
  • Responses:
    • 204 No Content: Integration tokens revoked successfully
    • 401 Unauthorized: Missing or invalid authentication token
    • 404 Not Found: Workspace or integration not found

Misc

GET /regions/postgres

Retrieve all available regions.

  • Responses:
    • 200 OK: Returns list of available/unsupported regions
    • 401 Unauthorized