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

Service tokens

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.

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 implements OAuth 2.0 with PKCE.

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

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

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 REST 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.