Skip to main content

OAuth 2.1 Reference

Detailed OAuth endpoint and payload reference for HG Insights integrations.

Intended Use​

Use OAuth when a third-party application needs user-delegated access (for example ChatGPT custom GPTs).

For direct integrations you control, use API key auth from Authentication.

Supported Flow​

  • Authorization Code flow
  • PKCE required (S256)
  • Dynamic Client Registration (RFC 7591)
  • Refresh token rotation
  • Token revocation (RFC 7009): the client authenticates and can revoke only tokens issued to it

Discovery Endpoints​

GET https://phoenix.hginsights.com/.well-known/oauth-authorization-server
GET https://phoenix.hginsights.com/.well-known/oauth-protected-resource

Use these endpoints at runtime instead of hardcoding server metadata.

OAuth Endpoints​

EndpointMethodPurpose
/.well-known/oauth-authorization-serverGETAuthorization server metadata
/.well-known/oauth-protected-resourceGETResource metadata
/oauth/registerPOSTDynamic client registration
/oauth/authorizeGETUser auth + consent
/oauth/tokenPOSTCode exchange and refresh
/oauth/revokePOSTToken revocation

Scopes​

ScopeDescription
mcp:readRead company data via MCP tools
mcp:toolsExecute MCP tools (default)
offline_accessIssue refresh tokens

Token Lifetimes​

  • Access token: 1 hour
  • Refresh token: 30 days
  • Authorization code: 10 minutes

Step-by-Step Flow​

1. Register Client​

POST https://phoenix.hginsights.com/oauth/register
Content-Type: application/json

{
"client_name": "My Application",
"redirect_uris": ["https://myapp.example.com/callback"],
"grant_types": ["authorization_code"],
"token_endpoint_auth_method": "none"
}

Example response:

{
"client_id": "phx_client_...",
"client_id_issued_at": 1706000000,
"redirect_uris": ["https://myapp.example.com/callback"],
"grant_types": ["authorization_code"],
"token_endpoint_auth_method": "none"
}

2. Redirect User to Authorization Endpoint​

https://phoenix.hginsights.com/oauth/authorize
?client_id=phx_client_...
&redirect_uri=https://myapp.example.com/callback
&response_type=code
&scope=mcp:tools offline_access
&state=random_state_value
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256

3. Exchange Authorization Code for Tokens​

POST https://phoenix.hginsights.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://myapp.example.com/callback
&client_id=phx_client_...
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Example response:

{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "def456...",
"scope": "mcp:tools offline_access"
}

4. Call OAuth-Protected MCP Endpoint​

POST https://phoenix.hginsights.com/api/ai/mcp
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Accept: application/json

OAuth requests use /api/ai/mcp (no API key in path).

5. Refresh Access Token​

POST https://phoenix.hginsights.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=def456...
&client_id=phx_client_...

HG Insights rotates refresh tokens. A new refresh token is returned and the previous one is invalidated.

6. Revoke Token​

Send the access or refresh token together with your client_id. Revocation authenticates the client the same way the token endpoint does (revocation_endpoint_auth_methods_supported in the discovery document), and only revokes tokens issued to that client.

Public client (token_endpoint_auth_method: none):

POST https://phoenix.hginsights.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=def456...
&client_id=phx_client_...

Confidential client, secret in an HTTP Basic header (client_secret_basic):

POST https://phoenix.hginsights.com/oauth/revoke
Authorization: Basic base64(urlencode(client_id) ":" urlencode(client_secret))
Content-Type: application/x-www-form-urlencoded

token=def456...
&client_id=phx_client_...

Confidential client, secret in the body (client_secret_post): send client_secret=... in the body instead of the header. Sending both at once is rejected.

client_id is required in the body even when you authenticate with a Basic header.

ResultStatus
Token revoked, or unknown / already revoked200, empty body
Missing token or client_id, malformed parameters, or a parameter repeated in a form or multipart body (a repeated JSON key keeps its last value)400 invalid_request
Token was issued to a different client (it stays valid)400 unauthorized_client
Unknown client, or wrong / missing secret401 invalid_client
Body over 16 KiB413 invalid_request
Too many requests from your IP429, with Retry-After
Temporary server problem (the token is not yet revoked; retry)503 server_error, with Retry-After

Error Format​

OAuth endpoints return:

{
"error": "invalid_request",
"error_description": "Missing code_verifier parameter (PKCE required)"
}

Common errors:

ErrorDescription
invalid_requestMissing or invalid parameter
invalid_clientUnknown client ID, or wrong / missing client secret
unauthorized_clientRevoke of a token that was issued to a different client
invalid_grantInvalid/expired/used code or refresh token
unsupported_grant_typeOnly authorization_code and refresh_token are accepted
unsupported_response_typeOnly code is accepted
invalid_client_metadataInvalid registration payload
server_errorInternal error; on revoke this is a retryable 503 with Retry-After

HTTP status on POST /oauth/token: server_error is returned with HTTP 500 and the generic description An unexpected error occurred. A failed client authentication at the endpoint (unknown client, missing or wrong credentials: invalid_client) is HTTP 401. Every other error, including a malformed request body (invalid_request), is HTTP 400.