Authentication

The Management API supports two authentication methods:

• Service Tokens - Simple bearer tokens for server-to-server integrations
• OAuth 2.0 - For user-facing applications requiring user consent

Service tokens

Service tokens are the simplest way to authenticate. They're ideal for scripts, CI/CD pipelines, and backend services.

Creating a Service token

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

Using a Service token

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",
});

OAuth 2.0

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

PKCE Support

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

This provides enhanced security, especially for mobile and single-page applications that cannot securely store client secrets.

Creating an OAuth Application

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

OAuth Endpoints

Available Scopes

Token Lifetimes

OAuth Authorization Flow

1. Redirect users to authorize

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.

2. Receive the authorization code

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

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

3. Exchange the code for an access token

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 Management API:

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

4. Use the access token

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

Token Refresh

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"

Using OAuth with the SDK

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

Using API Clients

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