apps/docs/content/docs/management-api/partner-integration.mdx
This guide walks you through building a partner integration with the Management API to power experiences like the npx create-db command.
You'll learn how to provision a Prisma Postgres database on your workspace as a partner, and how to transfer it to another user's workspace so they can "claim" the database. We'll cover how the process is secured using OAuth2, and by the end, you'll understand the full flow and how to integrate it into your own product experience.
This guide references the actual implementation in the npx create-db CLI and Cloudflare Workers as real world examples. The repo for the npx create-db is here, which can be used as a reference for how to use the Management API in your own projects.
:::note[How does this fit into your app?] The two Cloudflare Workers in this guide are just reference examples. You would typically build this logic into your own backend or serverless functions.
Similarly, the npx create-db CLI is a simple demo. In your product, you can trigger the same API calls from your own UI or onboarding flows to create a seamless experience for your users.
:::
Before diving into implementation, let's clarify the main concepts involved in the Management API integration:
To use the Prisma Postgres Management API, you first need to set up as a partner:
For a complete list of available endpoints and details on request/response formats, see the Prisma Management API documentation.
To obtain a client ID and client secret, you need go through this flow:
On the next screen, you can access and save the client ID and client secret for your OAuth app.
To provision a new Prisma Postgres database for your users as a partner, follow these steps:
POST request to the Management API endpoint to create a new project with a default database. For example:
const prismaResponse = await fetch("https://api.prisma.io/v1/projects", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer <YOUR_SERVICE_TOKEN>`,
},
body: JSON.stringify({ region, name }),
});
project_id. Store these securely and display them to your user as needed.project_id with your user in your own database for future reference.Once a database is provisioned, you may want to transfer ownership to your user at a later point so they can manage it in their own Prisma workspace and go beyond the free database usage limits. This is done via the claim flow, which consists of three main steps:
When a user wants to claim a database, your app will:
This ensures the transfer is secure and only the intended user can claim the database.
When your user wants to take ownership of a database you provisioned for them, they need to transfer it to their own Prisma Postgres workspace. This gives them full control over it.
To initiate this process, provide a button or link in your app (e.g., "Claim Database" or "Transfer to My Workspace"). When clicked, your backend should:
state value to track the session and prevent CSRF attacks.Example:
const authParams = new URLSearchParams({
client_id: YOUR_CLIENT_ID,
redirect_uri: "https://your-app.com/auth/callback", // Your callback endpoint
response_type: "code",
scope: "workspace:admin", // The scope of the OAuth2 authorization
state: generateState(), // Securely track the session
});
const authUrl = `https://auth.prisma.io/authorize?${authParams.toString()}`;
// Redirect the user to authUrl
The user will be prompted to log in (if not already authenticated) and select the workspace where they want to claim the database. After successful authentication and workspace selection, Prisma Auth will redirect back to your callback endpoint with a code and state (and, in some cases, a project_id).
Your backend should now:
const tokenResponse = await fetch("https://auth.prisma.io/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "authorization_code",
code: code, // The code received from the callback
redirect_uri: "https://your-app.com/auth/callback", // Must match the redirect_uri used in step 1
client_id: YOUR_CLIENT_ID,
client_secret: YOUR_CLIENT_SECRET,
}).toString(),
});
const tokenData = await tokenResponse.json();
project_id and the user's access token:const transferResponse = await fetch(`https://api.prisma.io/v1/projects/${project_id}/transfer`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${PRISMA_SERVICE_TOKEN}`,
},
body: JSON.stringify({ recipientAccessToken: tokenData.access_token }),
});
If the transfer is successful, the database is now owned by the user's workspace.
By following this guide, you have learned how to:
This flow enables you to integrate Prisma Postgres provisioning and transfer seamlessly into your own product, providing a smooth onboarding experience for your users.
For further details, see the create-db repo for a reference implementation, or consult the Prisma Management API documentation.