---
title: 'Management API'
metaTitle: 'Prisma Postgres: Management API Reference'
metaDescription: 'Management API reference documentation for Prisma Postgres.'
---

## Overview

This page covers the Prisma Management API which enables you to programmatically manage [platform](/platform/about) resources (e.g. projects or Prisma Postgres instances) in [Prisma Console](https://console.prisma.io). 

:::tip OpenAPI
An interactive [**OpenAPI 3.1 specification** is available here](https://api.prisma.io/v1/swagger-editor), 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:

- [Getting started with the Prisma Management API](/guides/management-api-basic)
- [Provisioning preview databases with GitHub Actions and Prisma Postgres](/guides/github-actions)
- [Partner database provisioning & user claim flow](/guides/management-api)
:::

## 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](https://console.prisma.io) 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](https://console.prisma.io/).
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](https://console.prisma.io).
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"
  }
  ```
- **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`

### 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`

{/* ## Management API playground

You can explore and interact with all endpoints in a live Swagger UI playground.

:::note
Use your service token or OAuth 2.0 access token to authorize requests in the UI.
:::

<iframe
  src="https://api.prisma.io/v0/swagger-editor"
  style={{
    width: '100%',
    height: '100vh', // This makes it take up the full viewport height
    border: '1px solid #ccc',
    borderRadius: '8px',
    overflow: 'hidden'
  }}
  title="Prisma API Swagger Editor"
></iframe> */}