OAuth 2.1 Reference
Detailed OAuth endpoint and payload reference for Phoenix 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 behavior: always returns
200)
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
| Endpoint | Method | Purpose |
|---|---|---|
/.well-known/oauth-authorization-server | GET | Authorization server metadata |
/.well-known/oauth-protected-resource | GET | Resource metadata |
/oauth/register | POST | Dynamic client registration |
/oauth/authorize | GET | User auth + consent |
/oauth/token | POST | Code exchange and refresh |
/oauth/revoke | POST | Token revocation |
Scopes
| Scope | Description |
|---|---|
mcp:read | Read company data via MCP tools |
mcp:tools | Execute MCP tools (default) |
offline_access | Issue 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_...
Phoenix rotates refresh tokens. A new refresh token is returned and the previous one is invalidated.
6. Revoke Token
POST https://phoenix.hginsights.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded
token=eyJhbGciOi...
Error Format
OAuth endpoints return:
{
"error": "invalid_request",
"error_description": "Missing code_verifier parameter (PKCE required)"
}
Common errors:
| Error | Description |
|---|---|
invalid_request | Missing or invalid parameter |
invalid_client | Unknown client ID |
invalid_grant | Invalid/expired/used code or refresh token |
unsupported_grant_type | Only authorization_code and refresh_token are accepted |
unsupported_response_type | Only code is accepted |
invalid_client_metadata | Invalid registration payload |
server_error | Internal error |