OIDC Reference

Reference for the Hawcx OpenID Connect provider. All endpoints are served from api.hawcx.com; the issuer is https://api.hawcx.com.

Discovery

Key discovery values:

scopes_supported and claims_supported above list the OIDC values relevant to interactive sign-in. The live document also advertises the machine-to-machine scopes used by the client-credentials and token-exchange grants (users:*, consent:*, audit:read, profile:self), and claims_supported additionally enumerates the ID-token claims (iss, aud, iat, sid, amr, and so on).

Authorization request

GET /authorize

On success the browser is redirected to redirect_uri with code and state. Errors on an unvetted client_id/redirect_uri render an error page (no redirect); other errors redirect with error and error_description.

Token request

POST /oauth2/token (application/x-www-form-urlencoded)

Response 200:

{
  "access_token": "<JWS>",
  "id_token": "<JWS>",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "email openid"
}

• id_token — the OIDC ID token you verify to authenticate the user (claims below). Signed ES512.
• access_token — an RFC 9068 at+jwt whose aud is the issuer. Its only use is calling UserInfo; it is not a credential for your own APIs and cannot be replayed against any other Hawcx service.
• expires_in — the access token's lifetime in seconds (default 300, configurable per client, clamped 1..3600). The ID token has its own separate lifetime (see Client configuration).
• scope — the scopes actually granted (the intersection of what you requested with scopes_supported).

Errors use the standard OAuth envelope: invalid_request, invalid_client, invalid_grant (unknown / expired / already-used code, or PKCE mismatch), temporarily_unavailable.

For verifying the returned token in your backend, see ID Token Verification; for the full client_assertion construction, see private_key_jwt authentication.

UserInfo request

GET /userinfo

Returns the OIDC standard claims for the signed-in user. Present the access_token from the token response as a bearer token; a stock OIDC client library calls this automatically after the token exchange.

curl https://api.hawcx.com/userinfo \
  -H "Authorization: Bearer <access_token>"

• Requires the access_token (not the ID token): the endpoint pins typ=at+jwt, requires aud to equal the issuer, and requires the openid scope.
• The route is keyless and CORS-enabled, so a browser-based SPA may call it cross-origin directly (see CORS). No client key or X-Config-Id header is needed.
• Response is application/json. Which claims appear depends on the granted scopes (profile, email, phone, address) and on what data exists for the user; absent claims are omitted rather than returned as null.

Response 200:

{
  "sub": "<stable user id>",
  "name": "Ada Lovelace",
  "given_name": "Ada",
  "family_name": "Lovelace",
  "email": "[email protected]",
  "email_verified": true,
  "phone_number": "+15551234567",
  "birthdate": "1815-12-10",
  "address": { "locality": "London", "country": "GB" },
  "locale": "en-US",
  "zoneinfo": "Europe/London",
  "updated_at": 1723200000
}

Errors: a missing bearer token returns a bare 401 challenge (WWW-Authenticate: Bearer, no error body); a present-but-rejected token — expired, wrong aud, or an ID token supplied instead of an access token — returns 401 invalid_token; a token passed as a query parameter returns 400 invalid_request; and a token that lacks the openid scope returns 403 insufficient_scope.

CORS

The four browser-reachable endpoints — /.well-known/openid-configuration, /.well-known/jwks.json, /oauth2/token, and /userinfo — send CORS headers and answer OPTIONS preflight, so a browser SPA can run the whole flow client-side.

Because the token and UserInfo allowlists are derived from your registered redirect_uris, there is no separate CORS origin list to maintain — add the SPA's origin as a redirect URI and it is allowed.

ID token claims

End-session request

GET /oauth2/end_session. See Single Logout.

Logout token claims

Delivered as a form-POST logout_token (a Security Event Token, RFC 8417; typ: secevent+jwt) to a client's backchannel_logout_uri, per OpenID Connect Back-Channel Logout 1.0.

Client configuration

Configured per client under Settings → OAuth (Admin Console).

Project-level, under Session policy: