Skip to main content

Authentication

Phoenix supports two authentication methods:

  • API key for direct integrations you control
  • OAuth 2.1 (PKCE) for third-party apps acting on behalf of a user

Which Method Should I Use?​

Use CaseRecommended Method
MCP clients you configure directly (Cursor, Claude Code, Windsurf, n8n)API key
Server-to-server scripts and internal automationAPI key
ChatGPT custom GPTs and other user-consent integrationsOAuth 2.1
Multi-tenant SaaS where each user authorizes their own accountOAuth 2.1

Rule of thumb: Use API keys unless a third-party app needs user-delegated access.

API keys are the fastest way to get started.

Get Your API Key​

  1. Log in to Phoenix at phoenix.hginsights.com
  2. Navigate to MCP in the sidebar
  3. Copy your API key from that page
warning

Keep your API keys secure. Never commit them to version control or share them publicly.

Using API Keys​

MCP endpoints (API key in URL path)​

https://phoenix.hginsights.com/api/ai/{YOUR_API_KEY}/mcp
https://phoenix.hginsights.com/api/ai/{YOUR_API_KEY}/sse

MCP endpoint (Bearer token)​

For enterprise API gateways (e.g., Azure APIM) and server-to-server integrations, Phoenix exposes an MCP endpoint that accepts the API key as a Bearer token instead of in the URL path:

POST https://phoenix.hginsights.com/api/mcp
Authorization: Bearer phx_your_api_key_here

Both the URL-path (/api/ai/{key}/mcp) and Bearer token (/api/mcp) approaches provide access to the same MCP tools. Use Bearer token auth when your gateway or client manages credentials separately from URLs.

REST/Agents endpoints (Bearer token)​

For documented REST and Agents endpoints that accept API key auth, pass it as:

Authorization: Bearer phx_your_api_key_here

Example:

curl -H "Authorization: Bearer phx_your_api_key_here" \
  https://phoenix.hginsights.com/api/agents/v1/agents
important

API key bearer auth is not universal for every /api/* route in the webapp. Always follow the auth requirements in each endpoint's reference doc.

Security Checklist​

  • Rotate keys regularly — regenerate keys periodically and after any suspected compromise
  • Never commit to version control — use environment variables or secret managers
  • One key per integration — use separate keys for different applications to limit blast radius
  • Revoke unused keys — delete keys for decommissioned integrations

OAuth 2.1 Authentication​

Phoenix supports OAuth 2.1 Authorization Code flow with PKCE (S256) for third-party integrations.

Scopes​

ScopeDescription
mcp:readRead company data via MCP tools
mcp:toolsExecute MCP tools (default scope)
offline_accessIssue refresh tokens for long-lived access

Endpoints​

GET  /.well-known/oauth-authorization-server
GET  /.well-known/oauth-protected-resource
POST /oauth/register
GET  /oauth/authorize
POST /oauth/token
POST /oauth/revoke

Minimal Flow​

  1. Register a client at /oauth/register (or let the client auto-register).
  2. Redirect the user to /oauth/authorize with PKCE (code_challenge_method=S256).
  3. Exchange the authorization code at /oauth/token using code_verifier.
  4. Call the OAuth MCP endpoint with bearer token:
POST https://phoenix.hginsights.com/api/ai/mcp
Authorization: Bearer <access_token>
  1. Refresh tokens at /oauth/token (grant_type=refresh_token) as needed.

Token lifetimes:

  • Access tokens expire after 1 hour
  • Refresh tokens expire after 30 days

Full OAuth request/response examples:

Common Issues​

SymptomWhat to check
401 on /api/ai/{apiKey}/mcpAPI key format, key rotation, revoked key
401 on /api/ai/mcpMissing/invalid Authorization: Bearer <access_token>
invalid_request with PKCE messageInclude code_challenge/code_verifier and code_challenge_method=S256
invalid_request for redirect_uriRedirect URI must exactly match the registered URI
invalid_grant on token exchange/refreshCode or refresh token expired, revoked, or already used

For protocol-level troubleshooting, see OAuth 2.1 Reference.

Next Steps​