diff --git a/.github/workflows/lychee.yml b/.github/workflows/lychee.yml index 257b7dded9..696d160004 100644 --- a/.github/workflows/lychee.yml +++ b/.github/workflows/lychee.yml @@ -23,20 +23,16 @@ jobs: output: ../lychee/out.md args: > --cache - --max-cache-age 3h + --max-cache-age 5m --verbose --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.*' --exclude 'https://localhost.*' - --exclude 'https://dev.mysql.com/.*' - --exclude 'https://www.mysql.com/.*' - --exclude 'https://www.gnu.org/.*' - --exclude 'https://www.cockroachlabs.com/.*' + --exclude 'https://cockroachlabs.com' --exclude '^/.*' './**/*.md' './**/*.mdx' workingDirectory: "content" @@ -54,7 +50,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 5 minutes to avoid unnecessary requests, and speed up consecutive runs. ### 📊 Results Overview diff --git a/content/250-postgres/100-introduction/230-management-api.mdx b/content/250-postgres/100-introduction/230-management-api.mdx index a5a65cd0f5..dff73263cf 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,66 @@ 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**. +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" +``` -On the next screen, copy and store the client ID and client secret for your OAuth app in a secure location. +:::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. +::: -### Example +Once you have an access token from the response, 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 +131,13 @@ 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 + - **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. @@ -360,7 +390,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 +412,7 @@ Retrieve all available regions. - `200 OK`: Returns list of available/unsupported regions - `401 Unauthorized` - +> */} \ No newline at end of file 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).