Platform API Keys

Audience: Phoenix Security users (Registered, Pro, Enterprise) — Last updated: 2026-07-14

This guide explains how to generate, use, and manage your Phoenix Security platform API keys directly from your account dashboard — without needing admin intervention.

1. What is a Platform API Key?

A platform API key authenticates your applications, scripts, and CI pipelines when they call Phoenix Security APIs. There are four categories, each for a different purpose — and a different key prefix so they can be rate-limited and revoked independently:

2. Generating a Key

1. Sign in to https://phxintel.security (or https://phxintel.appsecphoenix.io for pre-prod).
2. Click your avatar → Dashboard → My Account tab.
3. Scroll to Platform API Keys.
4. Pick a category card: Vulnerability Fetch, MCP Client, Malware Firewall, or Webhook Ingress.
   Cards your tier doesn't include are disabled with a tooltip explaining what tier unlocks them.
5. Enter a Name (e.g. prod-scanner, gha-firewall, github-pr-webhook), pick an Expires value (30–365 days), click Generate Key.
6. Copy the key immediately — the full secret is shown exactly once. Phoenix only stores a hash; if you lose the secret you must revoke and re-issue.

3. Using a Key

All keys are sent in the same header on every request:

X-API-Key: phx_api_basic_…

Authorization: ApiKey … and Authorization: Bearer phx_… are also accepted.

3.1 Vulnerability Fetch — REST

curl -H "X-API-Key: phx_api_basic_xxxx…" \
     https://phxintel.security/api/v1/cves/CVE-2024-3094

3.2 Vulnerability Fetch — GraphQL

curl -X POST https://phxintel.security/api/v1/graphql \
     -H "X-API-Key: phx_api_power_xxxx…" \
     -H "Content-Type: application/json" \
     -d '{"query":"{ cve(id: \"CVE-2024-3094\") { id ps_hp { score } } }"}'

3.3 MCP Client — Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "phoenix-security": {
      "url": "https://phxintel.security/api/v1/mcp",
      "headers": { "X-API-Key": "phx_mcp_xxxx…" }
    }
  }
}

3.4 Malware Firewall — CLI

export PHOENIX_FW_API_KEY=phx_fw_xxxx…
phoenix-firewall scan ./package-lock.json

3.5 Malware Firewall — GitHub Action

- uses: Security-Phoenix-demo/phoenix-firewall-action@v1
  with:
    api-key: ${{ secrets.PHOENIX_FW_API_KEY }}

3.6 Malware Firewall — retrieve rules and block from CLI

# List the rules attached to your account (what blocks what):
curl -H "X-API-Key: $PHOENIX_API_KEY" \
     https://phxintel.security/api/v1/firewall/rules

# Evaluate a package:
curl -X POST https://phxintel.security/api/v1/firewall/evaluate \
     -H "X-API-Key: $PHOENIX_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"packages":[{"ecosystem":"npm","name":"lodash","version":"4.17.21"}]}'

3.7 Webhook Ingress — GitHub PR / GitLab MR

curl -X POST https://phxintel.security/api/v1/firewall/webhook/scan \
     -H "X-API-Key: phx_whk_xxxx…" \
     -H "Content-Type: application/json" \
     -d '{
       "source": "github-actions",
       "event_type": "pull_request",
       "repository": "acme/web",
       "ref": "refs/pull/42/head",
       "lockfiles": [{"path":"package-lock.json","content":"..."}],
       "callback_url": "https://ci.acme.com/hooks/phoenix"
     }'

4. Tier Matrix

Free-tier users do not get platform API keys. Upgrade to Registered for self-service.

5. Lifecycle

6. Security Best Practices

• Never commit a key to git. Store in .env, GitHub Actions secrets, or your secret manager.
• One key per environment (dev, staging, prod) — easy to revoke without taking down everything.
• One key per workload (CI vs. local laptop vs. production scanner) — fast blast-radius containment.
• Use short TTLs in CI; rotate every quarter.
• Use the Firewall category for phoenix-firewall calls, not a Fetch key — keeps rate-limit buckets isolated.
• Revoke immediately on suspected leak. Phoenix logs every use; check the "Uses" counter as a tampering signal.

7. Troubleshooting

8. FAQ

Can I share a key across my team?
No — each key is tied to the user who created it for audit purposes. Use a service account if you need shared credentials.

Is there a separate key for the Phoenix Firewall agent (phx_fwagent_*)?
Yes, but that key is provisioned via phoenix-firewall enroll — with an existing platform API key (phoenix-firewall enroll --api-key <phx_fw_ key>), with a one-time bootstrap token you self-generate (phoenix-firewall enroll --bootstrap-token <token>; see §9.4, flag-gated), or with a one-time bootstrap token issued by your global admin. None of these mint a raw agent key directly from this dashboard. Use a phx_fw_* Malware Firewall key for CLI / CI / agent-bridge flows.

What's the difference between phx_api_basic_ and phx_api_unl_?
Just the rate-limit tier. Endpoints and response payloads are identical (modulo tier-based field redaction enforced server-side by data_shield).

Can I get a key without expiry?
No. All self-service keys must expire (max 365 days). This is a security guard, not a billing limit.

9. Compatibility with phoenix-firewall CLI

The same phx_fw_* key works across all official Phoenix Firewall clients. Both repos read the key from the standard environment variable / config slot:

9.1 PUB-firewall (Go binary)

# Option A — env var (recommended for CI):
export PHOENIX_API_KEY=phx_fw_xxxxxxxx...
phoenix-firewall scan ./package-lock.json

# Option B — config.toml (recommended for laptops):
# ~/.config/phoenix-firewall/config.toml
api_key  = "phx_fw_xxxxxxxx..."
api_url  = "https://phxintel.security"

9.2 PUB-firewall-agents-hub (NPM packages)

export PHOENIX_API_KEY=phx_fw_xxxxxxxx...

npx @phoenix-security/cli scan ./package.json
npx @phoenix-security/cli install-hooks
npx @phoenix-security/mcp-firewall

9.3 GitHub Action

- uses: Security-Phoenix-demo/phoenix-firewall-action@v1
  with:
    api-key: ${{ secrets.PHOENIX_API_KEY }}

9.4 Self-service enrollment token (phx_fwenroll_*, single-use)

As an alternative to enroll --api-key, a logged-in user can generate a single-use enrollment token instead of handing a reusable phx_fw_* key to a device:

• UI: firewall install page → Generate enrollment token button.
• API: POST /api/v1/firewall/enrollment-tokens (JWT/cookie auth; see the Public REST API reference for the full request/response contract).
• Enroll with it: phoenix-firewall enroll --bootstrap-token <token>.

phoenix-firewall enroll --bootstrap-token phx_fwenroll_xxxxxxxx...

The token is prefixed phx_fwenroll_, is single-use (rejected on a second redemption attempt), and self-binding — the enrolling device binds itself to the token on first use, so no pre-registration step is required. Tokens expire after ttl_hours (default 168h / 7 days, max 720h / 30 days).

10. Related Documentation

• Public REST API reference
• MCP integration guide
• PAI Internal API (admin-only, linked for context)