Token & JWKS Reference

Endpoint, parameter, and claim reference for Hawcx's JWT-issuance and JWKS surfaces

This page documents Hawcx's token-issuance and JWKS endpoints, and the claim set carried by Hawcx-issued ID Tokens. For a walkthrough of how the pieces fit together, see the ID Token verification guide.

All endpoints are scoped per environment. The examples below use https://api.hawcx.com (production). Substitute the issuer URL for your environment as provided in the Admin Console.

Discovery Document

Hawcx provides this document as a convenience for OIDC-compatible JWT libraries that auto-fetch it. Verification works equally well by fetching the JWKS endpoint directly. See the JWKS Endpoint section below.

URL: {issuer}/.well-known/openid-configuration

Method: GET

Authentication: None.

The document is identical for every project served by a given environment.

Response Fields

Field	Type	Description
`issuer`	string	The issuer identifier. Equals the environment's issuer URL with no trailing slash.
`token_endpoint`	string	URL of the token endpoint.
`jwks_uri`	string	URL of the JSON Web Key Set used to verify ID Token signatures.
`subject_types_supported`	array	Always `["public"]`. The `sub` claim is the same opaque identifier for all relying parties.
`id_token_signing_alg_values_supported`	array	Algorithms advertised by the active signing key. One of `["ES256"]`, `["ES512"]`, or `["EdDSA"]`.
`scopes_supported`	array	Always `["openid", "profile", "email"]`.
`token_endpoint_auth_methods_supported`	array	Always `["none"]`. Caller identification is via the API gateway; no client secret is required or accepted at the token endpoint.
`claims_supported`	array	Claims that may appear in the ID Token.

Hawcx is not a full OpenID Provider. The discovery document omits authorization_endpoint, userinfo_endpoint, registration_endpoint, revocation_endpoint, response_types_supported, grant_types_supported, and code_challenge_methods_supported, since those describe a redirect flow Hawcx doesn't have. PKCE is still enforced at the token endpoint; only its discovery metadata is omitted. Use a JWT library, not a full OIDC client.

ID Token

ID Tokens are OIDC Core 1.0 §2-conformant signed JWTs. The signing algorithm matches the value advertised in the discovery document's id_token_signing_alg_values_supported field.

Claims

Claim	Type	Description
`iss`	string	The issuer URL. Must equal the discovery document's `issuer` field.
`sub`	string	Opaque, stable user identifier. Use this as the identity key linking your user records to Hawcx (most apps store it as a unique-indexed column and keep their own internal primary key).
`aud`	string	The project's Client ID (the audience your backend pins). Auto-generated as a UUID at project creation, renameable in the Admin Console. See Changing the audience value.
`iat`	integer	Issued-at time, Unix epoch seconds.
`nbf`	integer	Not-before time. Tokens are valid from this instant.
`exp`	integer	Expiration time. Default lifetime is 3600 seconds.
`jti`	string	Unique token identifier (UUIDv4). Use to detect replay.
`auth_time`	integer	Time when end-user authentication completed, Unix epoch seconds.
`nonce`	string	Echoed from the authentication request when supplied. Verify equality on the client. Omitted entirely when the auth request did not supply a nonce.
`amr`	array	Authentication Methods References per RFC 8176. Always includes `"swk"`. When MFA was performed, adds `"mfa"` plus the specific factor (`"otp"` for TOTP or email OTP, `"sms"` for SMS OTP).
`acr`	string	Authentication Context Class Reference. Always `urn:hawcx:pwdless:v1`.
`email`	string	User's email address. Present when known.
`email_verified`	boolean	`true` when `email` is present. Hawcx only stores verified addresses.
`phone_number`	string	OIDC Core §5.1 standard phone claim. Present when known.
`phone`	string	Legacy phone claim, emitted alongside `phone_number` during the deprecation window. New integrations should read `phone_number`.
`cnf`	object	Confirmation claim. When token binding is in use, contains `jkt`, the SHA-256 thumbprint of the JWK the token is bound to.

The previous top-level mfa_method claim has been removed. The factor used is now expressed inside amr per RFC 8176.

Token Endpoint

Hawcx's code-exchange endpoint. The request and response shapes resemble RFC 6749 §4.1.3 / §4.1.4, but the endpoint is Hawcx-specific: it does not issue an access_token (Hawcx has no UserInfo or proprietary API for an access token to access), and the authorization code originates from a Hawcx-proprietary auth flow rather than an OAuth authorize redirect.

URL: {issuer}/oauth2/token

Method: POST

Content-Type: application/x-www-form-urlencoded

Authentication: None at this endpoint. The PKCE code_verifier proves the caller possessed the original verifier when the code was minted; project identification is via the gateway header below.

Exchanges an authorization code for a signed ID Token. The code is single-use and short-lived.

Required Headers

Header	Description
`X-Config-Id`	Your Hawcx project credential. Injected automatically when you call through the Hawcx API gateway.
`Content-Type`	Must be `application/x-www-form-urlencoded`.

Request Parameters

Parameter	Type	Required	Description
`code`	string	Yes	The authorization code received from the Hawcx SDK at the end of the auth flow.
`code_verifier`	string	Yes	The PKCE verifier. The original random string whose S256 hash was supplied as `code_challenge` when the auth flow began. The challenge method must be `S256`; any other value was rejected at mint time.

Response Body

Field	Type	Description
`id_token`	string	A signed JWT containing the user's identity claims.
`token_type`	string	Always `"Bearer"`.
`expires_in`	integer	Lifetime of the `id_token`, in seconds.

Response Headers

Header	Value	Notes
`Cache-Control`	`no-store`	Per RFC 6749 §5.1. Prevents intermediaries from caching freshly minted tokens.
`Pragma`	`no-cache`	Per RFC 6749 §5.1, for HTTP/1.0 compatibility.

Token Endpoint Errors

Errors are returned as application/json with error and error_description fields, following OAuth 2.1 error conventions. The endpoint deliberately collapses several distinct failure modes into a uniform invalid_grant to avoid leaking which step failed.

HTTP Status	`error`	When it occurs
400	`invalid_request`	The `X-Config-Id` header is missing or refers to an unknown project.
400	`invalid_grant`	The authorization code was not found, has expired, has already been used, was minted without a PKCE challenge, has an unsupported challenge method, or the `code_verifier` does not match.
500	`server_error`	The project's OAuth configuration is incomplete (missing `issuer` or `client_id` in the project's OAuth settings), or the project's configured issuer does not match the environment's discovery issuer. Operational error; contact support.
503	`temporarily_unavailable`	The signer or the per-project Redis is temporarily unreachable. Safe to retry with backoff.

JWKS Endpoint

URL: {issuer}/.well-known/jwks.json

Method: GET

Authentication: None.

Returns the public keys used to verify ID Token signatures. This is the only Hawcx endpoint your JWT library needs to fetch in order to verify tokens.

Response Body

A standard JSON Web Key Set (RFC 7517):

{
  "keys": [
    {
      "kty": "EC",
      "kid": "5f8a...",
      "alg": "ES256",
      "use": "sig",
      "crv": "P-256",
      "x": "...",
      "y": "..."
    }
  ]
}

Field	Type	Description
`keys`	array	One or more public keys. Hawcx currently exposes a single key per environment.
`keys[].kid`	string	Key ID. Match against the `kid` in the ID Token's JWT header to select the verification key.
`keys[].alg`	string	Signing algorithm. One of `ES256`, `ES512`, `EdDSA`.
`keys[].use`	string	Always `"sig"`.
`keys[].kty`	string	Key type. `EC` for ES256/ES512, `OKP` for EdDSA.
`keys[].crv`	string	Curve. `P-256` for ES256, `P-521` for ES512, `Ed25519` for EdDSA.
`keys[].x`, `keys[].y`	string	Public key coordinates, base64url-encoded. (`y` is omitted for EdDSA.)

JWKS Endpoint Errors

HTTP Status	`error`	When it occurs
503	`temporarily_unavailable`	The signer is unreachable or the backing KMS key cannot be read. Safe to retry with backoff.
503	`server_error`	The JWKS source is misconfigured. Operational error; contact support.

Token & JWKS Reference

On this page