Python SDK API Reference

from hawcx_oauth_client import HawcxOAuth
import os

oauth = HawcxOAuth.from_issuer(
    os.environ['HAWCX_BASE_URL'],   # issuer URL (Base URL from Admin Console)
    os.environ['HAWCX_CONFIG_ID'],
    os.environ['HAWCX_CLIENT_ID'],  # expected `aud` on issued id_tokens
)

from hawcx_oauth_client import HawcxOAuth
import os

oauth = HawcxOAuth.from_issuer(
    os.environ['HAWCX_BASE_URL'],   # issuer URL (Base URL from Admin Console)
    os.environ['HAWCX_CONFIG_ID'],
    os.environ['HAWCX_CLIENT_ID'],  # expected `aud` on issued id_tokens
)

result = oauth.exchange_code(auth_code, code_verifier)
claims = result.claims

# claims['sub'] = user ID
# claims.get('email') = verified email (if present)

claims = oauth.verify_token(id_token)

import asyncio
from hawcx_oauth_client import HawcxOAuthAsync

async def main():
    async with await HawcxOAuthAsync.from_issuer(
        issuer,        # e.g. "https://api.hawcx.com"
        config_id,     # → X-Config-Id header on the token exchange
        client_id,     # → expected `aud` on issued id_tokens
    ) as oauth:
        result = await oauth.exchange_code(auth_code, code_verifier)
        print(result.id_token, result.claims)

        claims = await oauth.verify_token(id_token, nonce=expected_nonce)

asyncio.run(main())

import os
from hawcx_oauth_client import StepUpClientAsync

async def change_mfa():
    async with StepUpClientAsync.with_private_key_jwt(
        oidc_signing_key=os.environ["HAWCX_OIDC_PRIVATE_KEY_PEM"],
        kid=os.environ["HAWCX_PRIVATE_KEY_KID"],
        client_id=os.environ["HAWCX_CLIENT_ID"],
        base_url="https://api.hawcx.com",
        config_id=os.environ["HAWCX_CONFIG_ID"],
    ) as client:
        started = await client.start_token(
            user_id="[email protected]",
            purpose="change_mfa_method",
            new_mfa_method="email_otp",
        )
        # ... user completes the MFA challenge, frontend returns a receipt ...
        await client.consume_receipt(receipt="receipt-from-frontend")

from hawcx_oauth_client import HawcxAsync

async def main():
    async with HawcxAsync(
        config_id="your-config-id",
        secret_key="hwx_sk_v1_...",
        base_url="https://api.hawcx.com",
    ) as hawcx:
        result = await hawcx.start_step_up(
            user_id="[email protected]",
            purpose="change_mfa_method",
            new_mfa_method="email_otp",
        )
        await hawcx.consume_step_up(receipt="receipt-from-frontend")

import os
from hawcx_oauth_client import StepUpClient

client = StepUpClient.with_private_key_jwt(
    oidc_signing_key=os.environ["HAWCX_OIDC_PRIVATE_KEY_PEM"],  # Ed25519 PEM or bytes
    kid=os.environ["HAWCX_PRIVATE_KEY_KID"],  # key id registered in the Hawcx Admin Console
    client_id=os.environ["HAWCX_CLIENT_ID"],
    base_url="https://api.hawcx.com",
    config_id=os.environ["HAWCX_CONFIG_ID"],
)

# Begin a step-up flow (purposes: "change_mfa_method", "change_phone_number")
result = client.start_token(
    user_id="[email protected]",
    purpose="change_mfa_method",
    new_mfa_method="email_otp",
)

# Finalize after the user completes the MFA challenge. The receipt is returned
# to your frontend by the Hawcx SDK once the challenge succeeds; forward it to
# your backend and pass it here.
receipt = "receipt-from-frontend-after-mfa"
client.consume_receipt(receipt=receipt)

# Generic call for any /v1/management/* endpoint
client.management_request(
    endpoint="/v1/management/users/mfa-enforcement",
    payload={"userid": "[email protected]"},
)

from hawcx_oauth_client import ResponseSignatureError

try:
    client.consume_receipt(receipt=receipt)
except ResponseSignatureError:
    # Missing or invalid signature: treat the response as untrusted. The server
    # has already processed the request, so reconcile state before retrying.
    raise

from hawcx_oauth_client import StepUpClient

client = StepUpClient.from_secret_key(   # DeprecationWarning is emitted
    secret_key="hwx_sk_v1_...",
    base_url="https://api.hawcx.com",
    api_key="your-config-id",
    tenant_header_name="X-Config-Id",
    tenant_header_value="your-config-id",
)

client.start_token(user_id="[email protected]", purpose="change_mfa_method")

from hawcx_oauth_client import Hawcx

hawcx = Hawcx(
    config_id="your-config-id",
    secret_key="hwx_sk_v1_...",
    base_url="https://api.hawcx.com",
)

result = hawcx.start_step_up(
    user_id="[email protected]",
    purpose="change_mfa_method",   # or "change_phone_number"
    new_mfa_method="email_otp",
)
hawcx.consume_step_up(receipt="receipt-from-frontend")

from hawcx_oauth_client import StepUpClient
import os

client = StepUpClient.with_private_key_jwt(
    oidc_signing_key=os.environ["HAWCX_OIDC_PRIVATE_KEY_PEM"],
    kid=os.environ["HAWCX_PRIVATE_KEY_KID"],
    client_id=os.environ["HAWCX_CLIENT_ID"],
    base_url="https://api.hawcx.com",
    config_id=os.environ["HAWCX_CONFIG_ID"],
)

# Read a user's MFA-enforcement preference
prefs = client.management_request(
    endpoint="/v1/management/users/mfa-enforcement",
    payload={"userid": "[email protected]"},
)

# Update it
client.management_request(
    endpoint="/v1/management/users/mfa-enforcement",
    payload={"userid": "[email protected]", "mfa_enforcement": "always"},
)

StepUpPurpose  = Literal["change_mfa_method", "change_phone_number"]
HxAuthMfaMethod = Literal["sms_otp", "email_otp", "totp"]

from hawcx_oauth_client import parse_hawcx_secret_key

creds = parse_hawcx_secret_key("hwx_sk_v1_...")  # -> ParsedCredentials

from hawcx_oauth_client import generate_credential_blob

blob = generate_credential_blob(
    kid=..., hkid=...,
    ed_private=..., x_private=...,        # 32-byte keys
    hawcx_ed_public=..., hawcx_x_public=...,
)  # -> "hwx_sk_v1_<base64url>"

CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

HawcxError                        # canonical root (message, error, error_description)
└── HawcxOAuthError               # back-compat alias — still catches every SDK error
    ├── DiscoveryError            # discovery document could not be resolved
    ├── TokenExchangeError        # token exchange failed (adds status_code)
    ├── TokenVerificationError    # signature / claims validation failed
    └── DelegationError           # base for delegation / step-up errors
        ├── DelegationCryptoError    # ECIES / signature / key-parsing failure
        ├── DelegationRequestError   # HTTP failure (adds status_code, response_body)
        └── DelegationResponseError  # response signature / timestamp / decryption check failed
            └── ResponseSignatureError  # X-Response-Signature missing or invalid (2.0.0+)

from hawcx_oauth_client import HawcxError, TokenExchangeError

try:
    result = oauth.exchange_code(auth_code, code_verifier)
except TokenExchangeError as e:
    log.warning("token exchange failed (HTTP %s)", e.status_code)
except HawcxError as e:
    log.error("Hawcx SDK call failed: %s", e)