Skip to main content

Authentication

HG Insights 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 HG Insights 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, HG Insights 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​

HG Insights 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.

Admin keys​

Org admins can mint a privileged admin API key that authorizes management operations (invite users, configure integrations) on the MCP, admin REST, and Power Automate surfaces. Admin keys are scoped to a single organization. Their admin tools work only while the user who minted the key still holds an admin role on at least one team in that organization — see Admin Operations → overview for the full security model, the audit log, and the available admin tools. If they lose the admin role but remain a member, the key is not revoked: over MCP and Power Automate it is treated as an ordinary user key, while the admin REST endpoints reject it. If they lose access to the organization altogether, all of their keys for it are revoked and stop authenticating.

Authorization: Bearer phx_<your-admin-key>

Admin keys use the same phx_ prefix as user keys; the distinction lives on the server side in webapp_api_keys_registry.scope.

An admin key exposes only the admin tools while its owner remains an org admin — the org's normal tools are not available to it, and vice versa. If you need both, keep two connections.

Once the owner no longer holds an admin role on any team, the admin tools stop working for the key: the admin REST endpoints and the Power Automate facade return 403 forbidden_admin_scope, and over MCP they disappear from tools/list. The key itself keeps working over MCP and Power Automate, falling back to user scope. If the owner loses access to the organization entirely, every key they hold for it is revoked and stops authenticating.

Next Steps​