From e30bfde90be0d43575522992e8aef4e27779590e Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 11:36:45 -0400 Subject: [PATCH 01/11] updated docs --- .../100-introduction/230-management-api.mdx | 84 +++++++++++-------- 1 file changed, 48 insertions(+), 36 deletions(-) diff --git a/content/250-postgres/100-introduction/230-management-api.mdx b/content/250-postgres/100-introduction/230-management-api.mdx index a5a65cd0f5..76de067126 100644 --- a/content/250-postgres/100-introduction/230-management-api.mdx +++ b/content/250-postgres/100-introduction/230-management-api.mdx @@ -20,7 +20,6 @@ We have three guides to help you use the Management API for common scenarios: - [Partner database provisioning & user claim flow](/guides/management-api) ::: - ## Base URL The base URL for a Prisma Postgres API request is: @@ -37,13 +36,16 @@ https://api.prisma.io/v1/projects/{projectId} ## Authentication -### Bearer tokens +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 -The Prisma Postgres API uses _Bearer Token Authentication_ and supports two kinds of tokens: -- Service tokens (manually created in your [Prisma Console](https://console.prisma.io) workspace) -- OAuth 2 access 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 adhere to the Bearer Token Authentication, you need to format your `Authorization` header like this: +To authenticate with a service token, include it in the `Authorization` header: ``` Authorization: Bearer $TOKEN @@ -51,38 +53,48 @@ Authorization: Bearer $TOKEN #### Creating a service token -You can create a service token to use the Management API like this: - 1. Open the [Prisma Console](https://console.prisma.io/). 2. Navigate to your workspace. -3. Navigate to the **Settings** page of your workspace and select **Service Tokens**. -4. Click **New Service Token**. -5. Copy the generated token and store it in a safe location for future use. +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, go through this flow: +To obtain a client ID and client secret: 1. Open the [Prisma Console](https://console.prisma.io). -1. Click the 🧩 **Integrations** tab in the sidenav. -1. In the **Published Applications** section, click the **New Application** button to start creating a new OAuth app. -1. Enter a **Name**, **Description**, and **Callback URL** for your OAuth app. -1. Click **Continue**. - -On the next screen, copy and store the client ID and client secret for your OAuth app in a secure location. +2. Click the 🧩 **Integrations** tab. +3. Under **Published Applications**, click **New Application**. +4. Enter a **Name**, **Description**, and **Callback URL**. +5. Click **Continue**, then copy and store your **Client ID** and **Client Secret**. + +#### Example: exchange a code for an access token + +```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" +``` -### Example +Once you have an access token, include it in requests to the Management API: -```terminal +```bash curl --location "https://api.prisma.io/v1/projects" \ -H "Accept: application/json" \ - -H "Authorization: Bearer $TOKEN" \ + -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ - --data \ - "{ - \"name\": \"my_project\", - \"region\": \"us-east-1\" - }" + --data '{ + "name": "my_project", + "region": "us-east-1" + }' ``` ### Instructions @@ -101,13 +113,14 @@ curl --location "https://api.prisma.io/v1/projects" \ 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 - - **Callback URL**: `http://localhost:8789/swagger/oauth2-redirect.html` - - **Auth URL** / **Access Token URL**: Your local OAuth URLs - - **Client ID / Secret**: From the script output - - **Scope**: (as needed) -1. After completing the flow, use the token in your requests. + - **Token Name**: Any name + - **Grant Type**: Authorization Code + - **Callback URL**: Your app’s redirect URI + - **Auth URL**: `https://auth.prisma.io/authorize` + - **Access Token URL**: `https://auth.prisma.io/token` + - **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. @@ -360,7 +373,6 @@ Retrieve integrations for the given workspace. - `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. @@ -383,7 +395,7 @@ Retrieve all available regions. - `200 OK`: Returns list of available/unsupported regions - `401 Unauthorized` - +> */} \ No newline at end of file From af557fd609d3409b0f850c8f9328ac7ce18b48e1 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 11:41:07 -0400 Subject: [PATCH 02/11] link updated --- content/800-guides/330-management-api-basic.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/800-guides/330-management-api-basic.mdx b/content/800-guides/330-management-api-basic.mdx index 3ba65b593c..83902dbd4e 100644 --- a/content/800-guides/330-management-api-basic.mdx +++ b/content/800-guides/330-management-api-basic.mdx @@ -12,7 +12,7 @@ community_section: true This guide walks you through setting up a basic TypeScript project that uses the [Prisma Postgres Management API](/postgres/introduction/management-api) to create a new [Prisma Console project](/platform/about#project) with a [Prisma Postgres](/postgres/introduction/overview) database, and print out all connection details. -You'll authenticate via a [service token](/postgres/introduction/management-api#bearer-tokens), set up your environment, and run a script to interact with the API. +You'll authenticate via a [service token](/postgres/introduction/management-api#service-tokens), set up your environment, and run a script to interact with the API. :::tip OpenApi The API reference is also available via an [OpenAPI 3.1. spec](https://api.prisma.io/v1/swagger-editor). From 226391fd0c2b913222052eac05647c4f191026ec Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 11:46:23 -0400 Subject: [PATCH 03/11] Buidl error fix --- content/250-postgres/100-introduction/230-management-api.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/250-postgres/100-introduction/230-management-api.mdx b/content/250-postgres/100-introduction/230-management-api.mdx index 76de067126..7a452a6121 100644 --- a/content/250-postgres/100-introduction/230-management-api.mdx +++ b/content/250-postgres/100-introduction/230-management-api.mdx @@ -70,7 +70,7 @@ To obtain a client ID and client secret: 2. Click the 🧩 **Integrations** tab. 3. Under **Published Applications**, click **New Application**. 4. Enter a **Name**, **Description**, and **Callback URL**. -5. Click **Continue**, then copy and store your **Client ID** and **Client Secret**. +5. Click **Continue**, then copy and store your **Client ID** and **Client Secret** to a secure location. #### Example: exchange a code for an access token @@ -117,7 +117,6 @@ curl --location "https://api.prisma.io/v1/projects" \ - **Grant Type**: Authorization Code - **Callback URL**: Your app’s redirect URI - **Auth URL**: `https://auth.prisma.io/authorize` - - **Access Token URL**: `https://auth.prisma.io/token` - **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. From e659d12a6205df789758bcd8fe84299effd6fec3 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 11:55:33 -0400 Subject: [PATCH 04/11] unrelated github action update --- .github/workflows/lychee.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index 257b7dded9..fcd9cc5187 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -28,7 +28,7 @@ jobs: --no-progress --accept 200,201,204,304,403,429 --timeout 20 - --max-retries 5 + --max-retries 8 --retry-wait-time 5 --max-concurrency 16 --exclude 'http://localhost.*' From d99e4b772c612a64141d499883cdfdd7ecc3f5c1 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 14:20:08 -0400 Subject: [PATCH 05/11] update clarity --- .../100-introduction/230-management-api.mdx | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/content/250-postgres/100-introduction/230-management-api.mdx b/content/250-postgres/100-introduction/230-management-api.mdx index 7a452a6121..dff73263cf 100644 --- a/content/250-postgres/100-introduction/230-management-api.mdx +++ b/content/250-postgres/100-introduction/230-management-api.mdx @@ -69,10 +69,24 @@ 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 **Callback URL**. +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. -#### Example: exchange a code for an access token +#### 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 \ @@ -84,7 +98,11 @@ curl -X POST https://auth.prisma.io/token \ -d "redirect_uri=$REDIRECT_URI" ``` -Once you have an access token, include it in requests to the Management API: +:::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" \ @@ -115,7 +133,7 @@ curl --location "https://api.prisma.io/v1/projects" \ 2. Click **Get New Access Token** and fill in the details: - **Token Name**: Any name - **Grant Type**: Authorization Code - - **Callback URL**: Your app’s redirect URI + - **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) From ee36b8fdbbc3bfcc4c7933e6cc7b6d57c42a7e86 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 15:22:44 -0400 Subject: [PATCH 06/11] caching max age adjusted --- .github/workflows/lychee.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index fcd9cc5187..c2ee1a930e 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -23,7 +23,7 @@ jobs: output: ../lychee/out.md args: > --cache - --max-cache-age 3h + --max-cache-age 10m --verbose --no-progress --accept 200,201,204,304,403,429 @@ -54,7 +54,7 @@ jobs: cat > lychee/formatted.md << 'EOF' ## 🍈 Lychee Link Check Report - > **Note:** Links are cached for 3 hours to avoid unnecessary requests, and speed up consecutive runs. + > **Note:** Links are cached for 10 minutes to avoid unnecessary requests, and speed up consecutive runs. ### 📊 Results Overview From e0f9b38fb0bdd1cbab937ddedec5a6b3d9b6d8fc Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 15:25:17 -0400 Subject: [PATCH 07/11] lychee params adjusted --- .github/workflows/lychee.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index c2ee1a930e..a3b581a1cd 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -22,8 +22,6 @@ jobs: fail: false output: ../lychee/out.md args: > - --cache - --max-cache-age 10m --verbose --no-progress --accept 200,201,204,304,403,429 @@ -33,10 +31,6 @@ jobs: --max-concurrency 16 --exclude 'http://localhost.*' --exclude 'https://localhost.*' - --exclude 'https://dev.mysql.com/.*' - --exclude 'https://www.mysql.com/.*' - --exclude 'https://www.gnu.org/.*' - --exclude 'https://www.cockroachlabs.com/.*' --exclude '^/.*' './**/*.md' './**/*.mdx' workingDirectory: "content" From f5fb4e0f41ad23ed7325da345bc4ea103c18db1d Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 15:55:11 -0400 Subject: [PATCH 08/11] cache size updates --- .github/workflows/lychee.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index a3b581a1cd..4c27e1c6d2 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -22,13 +22,14 @@ jobs: fail: false output: ../lychee/out.md args: > + --cache + --max-cache-age 5m --verbose --no-progress --accept 200,201,204,304,403,429 --timeout 20 --max-retries 8 --retry-wait-time 5 - --max-concurrency 16 --exclude 'http://localhost.*' --exclude 'https://localhost.*' --exclude '^/.*' @@ -48,7 +49,7 @@ jobs: cat > lychee/formatted.md << 'EOF' ## 🍈 Lychee Link Check Report - > **Note:** Links are cached for 10 minutes to avoid unnecessary requests, and speed up consecutive runs. + > **Note:** Links are cached for 5 minutes to avoid unnecessary requests, and speed up consecutive runs. ### 📊 Results Overview From f366872c3725cabc62fea1ebf0f625207cdf5829 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 15:59:59 -0400 Subject: [PATCH 09/11] lychee updates --- .github/workflows/lychee.yml | 38 +++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index 4c27e1c6d2..3a1d3053c5 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -32,13 +32,49 @@ jobs: --retry-wait-time 5 --exclude 'http://localhost.*' --exclude 'https://localhost.*' + --exclude 'https://cockroachlabs.com' --exclude '^/.*' './**/*.md' './**/*.mdx' workingDirectory: "content" env: GITHUB_TOKEN: ${{ secrets.github_token }} - - name: 📝 Clean up Lychee Report + - name: 🔄 Retry on Timeout + id: lychee-retry + if: ${{ always() }} + run: | + if [ -f "lychee/out.md" ] && grep -q "Timeout" lychee/out.md; then + echo "Timeout detected, retrying link check once..." + echo "retry=true" >> $GITHUB_OUTPUT + else + echo "retry=false" >> $GITHUB_OUTPUT + fi + + - name: 🍈 Lychee Link Checker (Retry) + if: ${{ steps.lychee-retry.outputs.retry == 'true' }} + uses: lycheeverse/lychee-action@v2 + with: + fail: false + output: ../lychee/out.md + args: > + --cache + --max-cache-age 5m + --verbose + --no-progress + --accept 200,201,204,304,403,429 + --timeout 20 + --max-retries 8 + --retry-wait-time 5 + --exclude 'http://localhost.*' + --exclude 'https://localhost.*' + --exclude 'https://cockroachlabs.com' + --exclude '^/.*' + './**/*.md' './**/*.mdx' + workingDirectory: "content" + env: + GITHUB_TOKEN: ${{ secrets.github_token }} + + - name: �📝 Clean up Lychee Report if: ${{ always() && github.event.pull_request.head.repo.fork == false }} run: | if [ -f "lychee/out.md" ]; then From 4af56da3fd7a872c99d97db7b95ed6f8c9fa1843 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 16:09:57 -0400 Subject: [PATCH 10/11] retry removed --- .github/workflows/lychee.yml | 37 +----------------------------------- 1 file changed, 1 insertion(+), 36 deletions(-) diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index 3a1d3053c5..696d160004 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -39,42 +39,7 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.github_token }} - - name: 🔄 Retry on Timeout - id: lychee-retry - if: ${{ always() }} - run: | - if [ -f "lychee/out.md" ] && grep -q "Timeout" lychee/out.md; then - echo "Timeout detected, retrying link check once..." - echo "retry=true" >> $GITHUB_OUTPUT - else - echo "retry=false" >> $GITHUB_OUTPUT - fi - - - name: 🍈 Lychee Link Checker (Retry) - if: ${{ steps.lychee-retry.outputs.retry == 'true' }} - uses: lycheeverse/lychee-action@v2 - with: - fail: false - output: ../lychee/out.md - args: > - --cache - --max-cache-age 5m - --verbose - --no-progress - --accept 200,201,204,304,403,429 - --timeout 20 - --max-retries 8 - --retry-wait-time 5 - --exclude 'http://localhost.*' - --exclude 'https://localhost.*' - --exclude 'https://cockroachlabs.com' - --exclude '^/.*' - './**/*.md' './**/*.mdx' - workingDirectory: "content" - env: - GITHUB_TOKEN: ${{ secrets.github_token }} - - - name: �📝 Clean up Lychee Report + - name: 📝 Clean up Lychee Report if: ${{ always() && github.event.pull_request.head.repo.fork == false }} run: | if [ -f "lychee/out.md" ]; then From 93f1251ef8abc89266569d5cf7ec9bb319354346 Mon Sep 17 00:00:00 2001 From: Aidan McAlister Date: Wed, 22 Oct 2025 16:12:13 -0400 Subject: [PATCH 11/11] chore: trigger link checker workflow