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": [ { 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..4cc1da9c16 --- /dev/null +++ b/content/800-guides/450-management-api-api-clients.mdx @@ -0,0 +1,208 @@ +--- +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' +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 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 + +### 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 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 + +### 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", }, ],