Authentication (/docs/rest-api/authentication)

For the complete Prisma documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL.

Learn how to authenticate with the Prisma REST API using service tokens or OAuth 2.0

Location: REST API > Authentication

The REST API supports two authentication methods:

• Service Tokens - Bearer tokens for scripts, CI/CD pipelines, and backend services
• OAuth 2.0 - For user-facing applications requiring user consent

A service token is a bearer token you create once in Prisma Console and pass in the Authorization header. Use one for scripts, CI/CD pipelines, and backend services, where no user is present to grant consent.

1. Navigate to Prisma Console and log in
2. Select your workspace
3. Go to Settings → Service Tokens
4. Click New Service Token
5. Copy the generated token immediately and store it securely

Include the token in the Authorization header:

curl -X GET "https://api.prisma.io/v1/workspaces" \
  -H "Authorization: Bearer your-service-token"

Or with the SDK:

import { createManagementApiClient } from "@prisma/management-api-sdk";

const client = createManagementApiClient({
  token: "your-service-token",
});

[!WARNING] Service tokens never expire

Service tokens do not have an expiration date. That suits long-running integrations, but a leaked token stays valid until you revoke it. Store tokens in a secrets manager and revoke any token you no longer need.

OAuth 2.0 is required for applications that act on behalf of users. The API implements OAuth 2.0 with PKCE.

The OAuth implementation supports Proof Key for Code Exchange (PKCE) using the S256 code challenge method:

• Public clients (no client secret): PKCE is mandatory
• Confidential clients (with client secret): PKCE is optional, but if you start the flow with PKCE, it must be completed with PKCE

PKCE lets mobile and single-page applications, which cannot keep a client secret private, complete the flow without one.

1. Navigate to Prisma Console and log in
2. Click the Integrations tab in the left sidebar
3. Under "Published Applications", click New Application
4. Fill in your application details:
   • Name: Your application name
   • Description*: Brief description *(optional)
   • Redirect URI: Your callback URL (e.g., https://your-app.com/auth/callback)
5. Click Continue
6. Copy your Client ID and Client Secret immediately

[!NOTE] Development redirect URIs

For local development, the following redirect URIs are accepted with any port via wildcard matching:

• localhost (e.g., http://localhost:3000/callback)
• 127.0.0.1 (e.g., http://127.0.0.1:3000/callback)
• [::1] - IPv6 loopback (e.g., http://[::1]:3000/callback)

[!NOTE] The discovery endpoint provides OAuth server metadata that can be used for automatic client configuration. Many OAuth libraries support automatic discovery using this endpoint.

Redirect users to the authorization endpoint with the following query parameters:

https://auth.prisma.io/authorize?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&response_type=code&scope=workspace:admin

This will redirect the user to the Prisma authorization page where they can grant your application access to their workspace.

After authorization, users are redirected to your callback URL with a code parameter:

https://your-app.com/callback?code=abc123...

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"

The response will include an access token that can be used to make authenticated requests to the REST API:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

curl -X GET "https://api.prisma.io/v1/workspaces" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

If you requested the offline_access scope, you'll receive a refresh token. Use it to obtain new access tokens:

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 "refresh_token=$REFRESH_TOKEN" \
  -d "grant_type=refresh_token"

[!NOTE] Refresh token rotation

Refresh tokens use single-use rotation with replay attack detection. When you exchange a refresh token for a new access token, you'll receive a new refresh token in the response. The old refresh token is immediately invalidated. If an invalidated refresh token is used again, it indicates a potential security breach, and the system will revoke all tokens associated with that authorization.

The SDK handles the OAuth flow automatically. See the SDK documentation for implementation details.

You can also authenticate using popular API clients like Postman, Insomnia, or Yaak. See the Using API Clients guide for step-by-step instructions.

• Getting Started: Get started with the Prisma REST API by creating your first project and database
• Partner Integration: Build partner integrations that provision and transfer Prisma Postgres databases to users
• SDK: A TypeScript SDK for the Prisma Data Platform REST API. Use the simple client for direct API access, or the full SDK with built-in OAuth authentication and automatic token refresh
• Using API Clients: Use the REST API with popular API clients like Postman, Insomnia, and Yaak