Skip to main content

Management API

Overview​

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

OpenAPI

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

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

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

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. 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.
Authentication in SwaggerUI

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.

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: 
    {
      "region": "us-east-1",
      "name": "My Project"
    }
  • 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: 
    {
      "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: 
    {
      "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

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:

    {
      "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
Open in
Copy as Markdown
Open in Claude
Open in ChatGPT
Open in T3.chat
Edit in GitHub