From d0a97da0cf7ceb88777670841735792bd496ed82 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 30 Dec 2025 13:10:09 -0500 Subject: [PATCH 1/4] management api guide added --- .../450-management-api-api-clients.mdx | 209 ++++++++++++++++++ sidebars.ts | 19 +- 2 files changed, 215 insertions(+), 13 deletions(-) create mode 100644 content/800-guides/450-management-api-api-clients.mdx diff --git a/content/800-guides/450-management-api-api-clients.mdx b/content/800-guides/450-management-api-api-clients.mdx new file mode 100644 index 0000000000..f76fb71dcc --- /dev/null +++ b/content/800-guides/450-management-api-api-clients.mdx @@ -0,0 +1,209 @@ +--- +title: 'How to use the Management API with API Clients' +metaTitle: 'How to use the Management API with API Clients' +description: 'Learn how to use the Management API with API Clients' +sidebar_label: 'Management API in API Clients' +completion_time: '5 min' +image: '/img/guides/prisma-management-api-cover.png' +community_section: true +--- + +## Postman + +Postman is a popular API client with testing, collaboration, and automation features for working with REST APIs. + +### Prerequisites + +Before you begin, make sure you have: +- A [Prisma Console account](https://console.prisma.io) +- [Postman installed](https://www.postman.com/downloads/) + +### 1. Create an OAuth2 Application + +First, you'll need to register an OAuth2 application in Prisma Console: + +1. Navigate to [Prisma Console](https://console.prisma.io) and log in +2. Click the **🧩 Integrations** tab in the left sidebar +3. Under the "Published Applications" section, click **New Application** +4. Fill in your application details: + - **Name**: Postman API Client + - **Description**: Brief description of your application *(Optional)* + - **Redirect URI**: `https://oauth.pstmn.io/v1/callback` +5. Click **Continue** +6. **Important**: Copy your Client ID and Client Secret immediately and store them securely + +:::note +The redirect URI `https://oauth.pstmn.io/v1/callback` is Postman's default callback URL when using the "Authorize using browser" option. +::: + +### 2. Configure OAuth 2.0 in Postman + +Now you'll set up authentication in Postman: + +1. Open Postman and create a new HTTP request +2. Set the request method to **POST** +3. Set the URL to `https://api.prisma.io/v1/projects` +4. Navigate to the **Authorization** tab +5. Set **Auth Type** to **OAuth 2.0** +6. Under **Configure New Token**, enter the following values: + +| Parameter | Value | +| --- | --- | +| Token Name | Management API Token | +| Grant Type | Authorization Code | +| Callback URL | `https://oauth.pstmn.io/v1/callback` | +| Authorize in Browser | `true` *(checked)* | +| Auth URL | `https://auth.prisma.io/authorize` | +| Access Token URL | `https://auth.prisma.io/token` | +| Client ID | `your-client-id` | +| Client Secret | `your-client-secret` | +| Scope | `workspace:admin` | + +7. Click **Get New Access Token** +8. A browser window will open—complete the authorization flow +9. Return to Postman and click **Use Token** to attach it to your request +10. Verify that your new token appears under **Current Token** at the top of the Authorization tab + +### 3. Make your first request + +With authentication configured, you can now create a project: + +1. In the request body, select **raw** and **JSON** format +2. Add the following JSON payload: +```json +{ + "name": "My Postman Database", + "region": "us-east-1" +} +``` + +3. Click **Send** + +You should receive a successful response confirming your project creation. + +## Insomnia + +Insomnia is an open-source API client with a clean interface for testing and debugging HTTP requests. + +### Prerequisites + +Before you begin, make sure you have: +- A [Prisma Console account](https://console.prisma.io) +- [Insomnia installed](https://insomnia.rest/download/) + +### 1. Create an OAuth2 Application + +First, you'll need to register an OAuth2 application in Prisma Console: + +1. Navigate to [Prisma Console](https://console.prisma.io) and log in +2. Click the **🧩 Integrations** tab in the left sidebar +3. Under the "Published Applications" section, click **New Application** +4. Fill in your application details: + - **Name**: Insomnia API Client + - **Description**: Brief description of your application *(Optional)* + - **Redirect URI**: `https://app.insomnia.rest/oauth/redirect` +5. Click **Continue** +6. **Important**: Copy your Client ID and Client Secret immediately and store them securely + +:::note +Insomnia uses `https://app.insomnia.rest/oauth/redirect` as the default OAuth callback URL for local authentication flows. +::: + +### 2. Configure OAuth 2.0 in Insomnia + +Now you'll set up authentication in Insomnia: + +1. Open Insomnia and create a new HTTP request +2. Set the request method to **POST** +3. Set the URL to `https://api.prisma.io/v1/projects` +4. Navigate to the **Auth** tab +5. Set the authentication type to **OAuth 2.0** +6. Under **Configuration**, enter the following values: + +| Parameter | Value | +| --- | --- | +| Grant Type | Authorization Code | +| Authorization URL | `https://auth.prisma.io/authorize` | +| Access Token URL | `https://auth.prisma.io/token` | +| Client ID | `your-client-id` | +| Client Secret | `your-client-secret` | +| Redirect URL | `https://app.insomnia.rest/oauth/redirect` | +| Scope *(Under Advanced Options)* | `workspace:admin` | + +7. Click **Fetch Tokens** +8. A browser window will open—complete the authorization flow +9. Return to Insomnia and verify that the access token has been retrieved +10. The token will be automatically attached to your requests + +### 3. Make your first request + +With authentication configured, you can now create a project: + +1. Navigate to the **Body** tab and select **JSON** format +2. Add the following JSON payload: +```json +{ + "name": "My Insomnia Database", + "region": "us-east-1" +} +``` + +3. Click **Send** + +You should receive a successful response confirming your project creation. + +## Yaak + +Yaak is a lightweight, native API client focused on speed and a minimal interface. + +### Prerequisites + +Before you begin, make sure you have: +- A [Prisma Console account](https://console.prisma.io) +- [Yaak installed](https://yaak.app) + +### 1. Create a service token + +First, you'll need to generate a service token from Prisma Console: + +1. Navigate to [Prisma Console](https://console.prisma.io) and log in +2. Select your workspace +3. Go to **Settings → Service Tokens** +4. Click **New Service Token** +5. **Important**: Copy the generated token immediately and store it securely + +### 2. Configure authentication in Yaak + +Now you'll set up authentication in Yaak: + +1. Open Yaak and create a new HTTP request +2. Set the request method to **POST** +3. Set the URL to `https://api.prisma.io/v1/projects` +4. Navigate to the **Headers** tab +5. Add the following headers: + +| Header Name | Value | +| --- | --- | +| Authorization | `Bearer your-service-token` | +| Content-Type | `application/json` | + +:::note +Replace `your-service-token` with the service token you generated in step 1. You can use Yaak's secure variable feature by clicking the **secure** option when entering the token value. +::: + +### 3. Make your first request + +With authentication configured, you can now create a project: + +1. Navigate to the **Body** tab and select **JSON** format +2. Add the following JSON payload: +```json +{ + "name": "My Yaak Database", + "region": "us-east-1" +} +``` + +3. Click **Send** + +You should receive a successful response confirming your project creation. \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 616d8bcc6f..bd012584c1 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -384,6 +384,7 @@ const sidebars: SidebarsConfig = { "guides/data-dog", "guides/github-actions", "guides/bun", + "guides/management-api-api-clients", ].sort(), }, { @@ -432,10 +433,7 @@ const sidebars: SidebarsConfig = { label: "Connection Pooling Guides", collapsed: false, collapsible: false, - items: [ - "guides/supabase-accelerate", - "guides/neon-accelerate", - ].sort(), + items: ["guides/supabase-accelerate", "guides/neon-accelerate"].sort(), }, { type: "category", @@ -499,9 +497,7 @@ const sidebars: SidebarsConfig = { label: "Vibe Coding Tutorials", collapsed: false, collapsible: false, - items: [ - "ai/tutorials/linktree-clone", - ], + items: ["ai/tutorials/linktree-clone"], }, { type: "category", @@ -551,8 +547,7 @@ const sidebars: SidebarsConfig = { }, { type: "link", - label: - "Vibe Coding an E-commerce App with Prisma MCP and Next.js", + label: "Vibe Coding an E-commerce App with Prisma MCP and Next.js", href: "https://www.prisma.io/blog/vibe-coding-with-prisma-mcp-and-nextjs", }, { @@ -570,14 +565,12 @@ const sidebars: SidebarsConfig = { items: [ { type: "link", - label: - "Automate your workflows with Prisma Postgres and 2,800+ apps", + label: "Automate your workflows with Prisma Postgres and 2,800+ apps", href: "https://pipedream.com/apps/prisma-management-api", }, { type: "link", - label: - "Prompt your application with Firebase Studio & Prisma Postgres", + label: "Prompt your application with Firebase Studio & Prisma Postgres", href: "/postgres/integrations/idx", }, ], From 4a940e59f6ddee72ce893a8ae7cd36f1eceb6f42 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 30 Dec 2025 13:12:02 -0500 Subject: [PATCH 2/4] non-existent og image removed --- content/800-guides/450-management-api-api-clients.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/content/800-guides/450-management-api-api-clients.mdx b/content/800-guides/450-management-api-api-clients.mdx index f76fb71dcc..4ebe75cdba 100644 --- a/content/800-guides/450-management-api-api-clients.mdx +++ b/content/800-guides/450-management-api-api-clients.mdx @@ -4,7 +4,6 @@ metaTitle: 'How to use the Management API with API Clients' description: 'Learn how to use the Management API with API Clients' sidebar_label: 'Management API in API Clients' completion_time: '5 min' -image: '/img/guides/prisma-management-api-cover.png' community_section: true --- From ad37e6e84e10915208a18b7d07415d6430ec1c83 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Tue, 30 Dec 2025 13:16:33 -0500 Subject: [PATCH 3/4] yaak added to spellcheck --- cSpell.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/cSpell.json b/cSpell.json index d66c5bbf0f..683170ccc2 100644 --- a/cSpell.json +++ b/cSpell.json @@ -172,7 +172,9 @@ "Dataguide", "justinellingwood", "Millis", - "Linktree" + "Linktree", + "Yaak", + "Yaak's" ], "patterns": [ { From 98ec9fda67ef2d54b940292ac1cb39f63bee20d0 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 31 Dec 2025 10:28:18 -0500 Subject: [PATCH 4/4] minor typo --- content/800-guides/450-management-api-api-clients.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/800-guides/450-management-api-api-clients.mdx b/content/800-guides/450-management-api-api-clients.mdx index 4ebe75cdba..4cc1da9c16 100644 --- a/content/800-guides/450-management-api-api-clients.mdx +++ b/content/800-guides/450-management-api-api-clients.mdx @@ -59,7 +59,7 @@ Now you'll set up authentication in Postman: | Scope | `workspace:admin` | 7. Click **Get New Access Token** -8. A browser window will open—complete the authorization flow +8. A browser window will open and have you complete the authorization flow 9. Return to Postman and click **Use Token** to attach it to your request 10. Verify that your new token appears under **Current Token** at the top of the Authorization tab @@ -130,7 +130,7 @@ Now you'll set up authentication in Insomnia: | Scope *(Under Advanced Options)* | `workspace:admin` | 7. Click **Fetch Tokens** -8. A browser window will open—complete the authorization flow +8. A browser window will open and have you complete the authorization flow 9. Return to Insomnia and verify that the access token has been retrieved 10. The token will be automatically attached to your requests