## 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 TypeScript SDK
The [`@prisma/management-api-sdk`](/postgres/introduction/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](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"
  }
  ```
- **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:your_password@db.prisma.io:5432/postgres?sslmode=require
  ```

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

  ```env
  DATABASE_URL="postgresql://your_user_id:your_password@db.prisma.io: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`

{/* ## 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> */}
---

# Management API SDK