Authentication
Authenticate with the Pie API using an API key or a bearer token. Most integrations use an API key.
| Method | Header | Use case |
|---|---|---|
| API key | X-API-Key: <key> | Programmatic access, CI/CD, MCP integrations |
| Bearer token | Authorization: Bearer <token> | Pie web app sessions. Use an API key for scripts, CI and agents |
API key authentication
Use an API key for programmatic access. Create one in Settings > API Keys (see Create an API key). Pie shows the key once, so store it when you create it.
Headers
| Header | Required | Description |
|---|---|---|
X-API-Key | Yes | Your API key. Pie resolves the app from the key. |
Example
curl -X GET "https://api.pie.inc/v1/test-cases" \
-H "X-API-Key: YOUR_API_KEY"Error responses
| Status | Message | Cause |
|---|---|---|
| 401 | Authentication required: provide either X-API-Key header or Authorization Bearer token | No X-API-Key header, and no Authorization header in the Bearer <token> form |
| 401 | Invalid API key | Key not found or has been revoked |
| 403 | API key cannot access the requested app | The API key doesn’t have access to the app the request asked for |
| 503 | Authentication service temporarily unavailable | Pie couldn’t check your credentials. Retry the request |
Bearer token authentication
A bearer token carries a signed-in session from the Pie web app. For scripts, CI and agents, use an API key instead.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <token>, where the token is a Pie web app session token |
X-App-ID | Yes* | Your app identifier. *Not required for /v1/apps. |
Example
curl -X GET "https://api.pie.inc/v1/apps" \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"curl -X GET "https://api.pie.inc/v1/test-cases" \
-H "Authorization: Bearer YOUR_SESSION_TOKEN" \
-H "X-App-ID: YOUR_APP_ID"Error responses
| Status | Message | Cause |
|---|---|---|
| 401 | Invalid Firebase ID token | The bearer token isn’t a valid or current Pie session token |
| 401 | X-App-ID header is required | Missing X-App-ID on endpoints that require it. The message continues: please hit /v1/apps to get the app ids you have access to |
| 401 | User does not have access to this app | User isn’t in the app’s permission list |
Common headers
Some endpoints also take these headers:
| Header | Description | Used by |
|---|---|---|
Content-Type: application/json | Required for POST, PUT and PATCH request bodies | All write endpoints |
Accept: text/csv | Requests a CSV response | GET endpoints (test cases, issues, results, runs) |
X-Export-Format: csv | Alternative CSV export trigger | GET endpoints |
MCP server authentication
The MCP server at https://mcp.pie.inc uses the same API key, sent in a header:
| Method | Format |
|---|---|
| Header | X-API-Key: YOUR_API_KEY |
For setup per platform (Claude Desktop, Cursor, VS Code, Claude Code), see Connect your agent.
Response format
All API responses use one envelope.
Success:
{
"success": true,
"status": 200,
"message": "Operation completed successfully",
"data": { ... }
}Error:
{
"success": false,
"status": 401,
"message": "Authentication required: provide either X-API-Key header or Authorization Bearer token"
}An error response has no data field. Some errors also carry an errorId.
Related
Last updated on