Authentication

Pie supports three authentication methods. The API checks them in priority order: Scheduler Secret > API Key > Firebase Bearer Token. Most integrations use API Key auth.

Quick Reference

Method	Header	Use Case
API Key	`X-API-Key: <key>`	Programmatic access, CI/CD, MCP integrations
Firebase Bearer Token	`Authorization: Bearer <token>`	Browser sessions, user-specific operations
Scheduler Secret	`X-API-Key: <secret>` + `X-App-ID: <id>`	Internal scheduled jobs

API Key Authentication

The primary method for programmatic access. Generate keys from the Pie dashboard.

Setup

Log in to app.pie.inc
Go to Settings > API Keys
Click + Create API Key
Name your key and click Create
Copy the key immediately - it won’t be shown again

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`X-App-ID`	No	Override app ID (admin users only). If omitted, uses the app associated with your key

Example

curl -X GET "https://api.pie.inc/v1/test-cases" \
  -H "X-API-Key: YOUR_API_KEY"

How It Works

The key is validated against the api-keys collection in Firestore
The app ID is automatically resolved from the key
Admin users (checked via Firebase Auth custom claims) can override the app with the X-App-ID header

Error Responses

Status	Message	Cause
401	`API key is required`	No `X-API-Key` header and no `Authorization` header provided
401	`Invalid API key`	Key not found in the database or has been revoked
403	`Only admin users can switch apps`	Non-admin user tried to use `X-App-ID` to override the app

Firebase Bearer Token Authentication

Used for browser-based sessions and user-specific operations like app setup.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <firebase_id_token>`
`X-App-ID`	Yes*	Your app identifier. *Not required for `/v1/apps` and `/v1/setup-app`

Example

curl -X GET "https://api.pie.inc/v1/apps" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

curl -X GET "https://api.pie.inc/v1/test-cases" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
  -H "X-App-ID: YOUR_APP_ID"

How It Works

The Firebase ID token is verified using Firebase Admin SDK
The user’s UID is extracted from the token
Access is validated against the userAppPermissions collection
Admin/superadmin users (via Firebase custom claims) bypass app access checks

Error Responses

Status	Message	Cause
401	`Authorization header is required`	No auth header provided
401	`Invalid authorization header format`	Header doesn’t follow `Bearer <token>` format
401	`X-App-ID header is required`	Missing `X-App-ID` on endpoints that require it
401	`Invalid Firebase ID token`	Token is expired, malformed, or revoked
401	`User does not have access to this app`	User not in the app’s permission list

Scheduler Secret Authentication

Used for internal scheduled jobs and automated pipelines. The secret is set via the SCHEDULER_SECRET_KEY environment variable on the server.

Headers

Header	Required	Description
`X-API-Key`	Yes	The scheduler secret value
`X-App-ID`	Yes	Target app identifier (always required for scheduler auth)

Example

curl -X POST "https://api.pie.inc/v1/discovery" \
  -H "X-API-Key: SCHEDULER_SECRET" \
  -H "X-App-ID: YOUR_APP_ID" \
  -H "Content-Type: application/json"

Error Responses

Status	Message	Cause
400	`X-App-ID header required for scheduler requests`	Missing `X-App-ID` header

Common Headers

These headers are used alongside authentication on specific endpoints:

Header	Description	Used By
`Content-Type: application/json`	Required for POST/PUT/PATCH request bodies	All write endpoints
`Accept: text/csv`	Request CSV format response	GET endpoints (test cases, issues, results, runs)
`X-Export-Format: csv`	Alternative CSV export trigger	GET endpoints

Admin Capabilities

Users with admin or superadmin roles (set via Firebase Auth custom claims) have additional capabilities:

App switching: Can use X-App-ID header with API Key auth to access any app
Bypass access checks: Skip userAppPermissions validation when using Bearer auth
MCP admin tools: Access to get_apps, search_apps, and switch_app MCP tools

MCP Server Authentication

The MCP server at https://mcp.pie.inc uses the same API Key authentication:

Method	Format
Header	`X-API-Key: YOUR_API_KEY`
Query parameter	`?api_key=YOUR_API_KEY`

For setup instructions per platform (Claude Desktop, Cursor, VS Code, Claude Code), see Connect Pie to Your AI Workspace.

Response Format

All API responses follow a standard envelope:

Success:

{
  "success": true,
  "status": 200,
  "message": "Operation completed successfully",
  "data": { ... }
}

Error:

{
  "success": false,
  "status": 401,
  "message": "API key is required",
  "data": null
}

Appendix Error Codes