Loading...
;
if (state.status === 'error') {
return (
Error: {state.error.message}
Success! Redirecting...
;
if (state.status === 'step') {
const { step } = state;
if (step.type === 'select_method') {
return (
Choose method
{step.methods.map((m) => ( ))}Set up authenticator
Or enter manually: {step.secret}
{step.qrData && }`})
}
);
}
if (step.type === 'redirect') {
window.location.href = step.url;
return Waiting for approval...
Redirecting...
;
}
return Step: {step.type}
;
}
return null;
}
```
---
## Web SDK — Vanilla JS Example
```typescript
import { createHawcxAuth } from '@hawcx/core';
const client = createHawcxAuth({ configId: 'your_config_id' });
client.onStateChange(renderUI);
function login(email: string) { client.start(email); }
function renderUI(state) {
const app = document.getElementById('app')!;
if (state.status === 'idle') {
app.innerHTML = `
`;
} else if (state.status === 'loading') {
app.innerHTML = 'Loading...
';
} else if (state.status === 'error') {
app.innerHTML = `Error: ${state.error.message}
`; } else if (state.status === 'completed') { fetch('/exchange', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ authCode: state.authCode, codeVerifier: state.codeVerifier }) }).then(() => window.location.href = '/'); app.innerHTML = 'Success! Redirecting...
';
} else if (state.status === 'step') {
const { step } = state;
if (step.type === 'select_method') {
app.innerHTML = `Choose method
${step.methods.map(m => ``).join('')}`; } else if (step.type === 'enter_code') { app.innerHTML = `Code sent to ${step.destination}
`; } else { app.innerHTML = `Step: ${step.type}
`;
}
}
}
(window as any).login = login;
(window as any).client = client;
```
---
## Node.js Backend SDK — Complete API
### HawcxOAuth
```typescript
import { HawcxOAuth } from '@hawcx/oauth-client';
// Recommended: discovery mode enforces iss + aud. Construct ONCE at startup and
// reuse (one-time discovery fetch); throws DiscoveryError at boot on a bad or
// unreachable issuer.
const oauth = await HawcxOAuth.fromIssuer({
issuer: process.env.HAWCX_BASE_URL!, // your environment's Base URL
configId: process.env.HAWCX_CONFIG_ID!, // sent as the X-Config-Id header
clientId: process.env.HAWCX_CLIENT_ID!, // expected `aud` on issued id_tokens
});
// Legacy (signature-only — no iss/aud check; optional baseUrl defaults to prod):
// const oauth = new HawcxOAuth({ configId, baseUrl, timeout });
```
### `exchangeCode(authCode, codeVerifier)`
```typescript
const { idToken, claims } = await oauth.exchangeCode(authCode, codeVerifier);
// claims.sub = user ID
// claims.email = verified email
```
Returns: `{ idToken: string, claims: { sub: string, email: string, ... } }`
### `verifyToken(token)` — verify a JWT and return claims
```typescript
const claims = await oauth.verifyToken(idToken);
```
### `refreshJwks()` — refresh JWKS cache
```typescript
oauth.refreshJwks(); // clearCache() is a deprecated alias (removed in 6.0.0)
```
### Error Types
```typescript
import { DiscoveryError, TokenExchangeError, TokenVerificationError } from '@hawcx/oauth-client';
// At startup — fromIssuer does the discovery fetch and can throw DiscoveryError:
try {
const oauth = await HawcxOAuth.fromIssuer({ issuer, configId, clientId });
} catch (error) {
if (error instanceof DiscoveryError) {
// Issuer unreachable or discovery document malformed. Fail startup loudly —
// this is a boot-time error, not something a per-request handler can catch.
}
}
// Per request — exchangeCode can throw TokenExchangeError / TokenVerificationError:
try {
const { claims } = await oauth.exchangeCode(authCode, codeVerifier);
} catch (error) {
if (error instanceof TokenExchangeError) {
// Code invalid, expired, or already used. Ask user to re-authenticate.
console.error(error.message, error.statusCode);
}
if (error instanceof TokenVerificationError) {
// JWT signature/claims failed. Log incident, re-authenticate.
console.error(error.message);
}
}
```
### Express.js Integration
```typescript
import express from 'express';
import { HawcxOAuth } from '@hawcx/oauth-client';
const app = express();
app.use(express.json());
const oauth = await HawcxOAuth.fromIssuer({
issuer: process.env.HAWCX_BASE_URL!, configId: process.env.HAWCX_CONFIG_ID!, clientId: process.env.HAWCX_CLIENT_ID!,
});
app.post('/exchange', async (req, res) => {
const { authCode, codeVerifier } = req.body;
if (!authCode || !codeVerifier) {
return res.status(400).json({ error: 'Missing authCode or codeVerifier' });
}
try {
const { claims } = await oauth.exchangeCode(authCode, codeVerifier);
// Create your own session — DO NOT use idToken as your access token
req.session.userId = claims.sub;
req.session.email = claims.email;
// Or use httpOnly cookies (recommended):
// const sessionToken = jwt.sign({ sub: claims.sub, email: claims.email }, SECRET, { expiresIn: '1h' });
// res.cookie('session', sessionToken, { httpOnly: true, secure: true, sameSite: 'strict' });
res.json({ success: true, userId: claims.sub });
} catch (error) {
console.error('Authentication failed:', error);
res.status(401).json({ error: 'Authentication failed' });
}
});
```
### Fastify Integration
```typescript
import Fastify from 'fastify';
import { HawcxOAuth } from '@hawcx/oauth-client';
const app = Fastify();
const oauth = await HawcxOAuth.fromIssuer({
issuer: process.env.HAWCX_BASE_URL!, configId: process.env.HAWCX_CONFIG_ID!, clientId: process.env.HAWCX_CLIENT_ID!,
});
app.post<{ Body: { authCode: string; codeVerifier: string } }>('/exchange', async (request, reply) => {
const { authCode, codeVerifier } = request.body;
try {
const { claims } = await oauth.exchangeCode(authCode, codeVerifier);
reply.send({ success: true, userId: claims.sub });
} catch (error) {
reply.status(401).send({ error: 'Authentication failed' });
}
});
```
### Step-Up Client (MFA Management)
Node's step-up surface is `StepUpClient` — `startToken` and `consumeReceipt` only (there is **no** `managementRequest` on it). A legacy ECIES `DelegationClient` / `MfaMethod` also exists in `@hawcx/oauth-client` (see the Node reference), but `StepUpClient.withPrivateKeyJwt` is preferred.
```typescript
import { StepUpClient } from '@hawcx/oauth-client';
const privateJwk = JSON.parse(process.env.HAWCX_PRIVATE_JWK!); // OKP/Ed25519, with kid
// Recommended: private_key_jwt (RFC 7523) — reuses your OIDC signing key
const stepUp = StepUpClient.withPrivateKeyJwt({
baseUrl: process.env.HAWCX_BASE_URL!,
configId: process.env.HAWCX_CONFIG_ID!,
clientId: process.env.HAWCX_CLIENT_ID!,
oidcSigningKey: privateJwk,
kid: privateJwk.kid,
});
// Begin a step-up flow
const { start_token, expires_in } = await stepUp.startToken({
userId: 'user@example.com',
purpose: 'change_mfa_method',
newMfaMethod: 'totp', // 'email_otp' | 'sms_otp' | 'totp'
});
// Finalize after the user completes the MFA challenge (receipt from your frontend)
const { ok } = await stepUp.consumeReceipt({ receipt: 'step-up-receipt-from-client' });
```
A legacy `StepUpClient.fromSecretKey({ secretKey: 'hwx_sk_v1_…', baseUrl })` (ECIES blob) also exists but is deprecated — prefer `withPrivateKeyJwt`.
---
## Python Backend SDK — Complete API
### HawcxOAuth
```python
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
)
# NOTE: Python has NO base_url constructor and no single-arg form — from_issuer
# (or HawcxOAuthAsync.from_issuer) is the only public entry point.
```
### `exchange_code(auth_code, code_verifier)`
```python
result = oauth.exchange_code(auth_code, code_verifier)
claims = result.claims
# claims['sub'] = user ID
# claims.get('email') = verified email
# result.id_token = raw JWT (do not use as access token)
```
### `verify_token(token)`
```python
claims = oauth.verify_token(id_token)
```
### Flask Integration
```python
from flask import Flask, request, jsonify, session
from hawcx_oauth_client import HawcxOAuth
import os
app = Flask(__name__)
app.secret_key = os.getenv('FLASK_SECRET_KEY')
oauth = HawcxOAuth.from_issuer(
os.environ['HAWCX_BASE_URL'], os.environ['HAWCX_CONFIG_ID'], os.environ['HAWCX_CLIENT_ID']
)
@app.route('/exchange', methods=['POST'])
def exchange():
data = request.json
auth_code = data.get('authCode')
code_verifier = data.get('codeVerifier')
if not auth_code or not code_verifier:
return jsonify({'error': 'Missing authCode or codeVerifier'}), 400
try:
result = oauth.exchange_code(auth_code, code_verifier)
claims = result.claims
session['user_id'] = claims['sub']
session['email'] = claims.get('email')
return jsonify({'success': True, 'userId': claims['sub']})
except Exception as error:
app.logger.error(f'Authentication failed: {error}')
return jsonify({'error': 'Authentication failed'}), 401
```
### Django Integration
```python
from django.http import JsonResponse
from django.views.decorators.http import require_http_methods
from hawcx_oauth_client import HawcxOAuth
import os
oauth = HawcxOAuth.from_issuer(
os.environ['HAWCX_BASE_URL'], os.environ['HAWCX_CONFIG_ID'], os.environ['HAWCX_CLIENT_ID']
)
@require_http_methods(["POST"])
def exchange(request):
auth_code = request.POST.get('authCode')
code_verifier = request.POST.get('codeVerifier')
if not auth_code or not code_verifier:
return JsonResponse({'error': 'Missing authCode or codeVerifier'}, status=400)
try:
result = oauth.exchange_code(auth_code, code_verifier)
claims = result.claims
request.session['user_id'] = claims['sub']
return JsonResponse({'success': True, 'userId': claims['sub']})
except Exception:
return JsonResponse({'error': 'Authentication failed'}, status=401)
```
### FastAPI Integration
```python
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from hawcx_oauth_client import HawcxOAuth
import os
app = FastAPI()
oauth = HawcxOAuth.from_issuer(
os.environ['HAWCX_BASE_URL'], os.environ['HAWCX_CONFIG_ID'], os.environ['HAWCX_CLIENT_ID']
)
@app.post('/exchange')
async def exchange(payload: dict):
auth_code = payload.get('authCode')
code_verifier = payload.get('codeVerifier')
if not auth_code or not code_verifier:
return JSONResponse({'error': 'Missing authCode or codeVerifier'}, status_code=400)
try:
result = oauth.exchange_code(auth_code, code_verifier)
claims = result.claims
return JSONResponse({'success': True, 'userId': claims['sub'], 'email': claims.get('email')})
except Exception:
return JSONResponse({'error': 'Authentication failed'}, status_code=401)
```
### Python Step-Up Client (MFA Management)
Python's management surface is `StepUpClient` — `start_token`, `consume_receipt`, and a
generic `management_request`. There is **no** `HawcxDelegationClient` / `MfaMethod`.
```python
import os
from hawcx_oauth_client import StepUpClient
# Recommended: private_key_jwt (RFC 7523) — reuses your OIDC signing key
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'],
client_id=os.environ['HAWCX_CLIENT_ID'],
base_url=os.environ['HAWCX_BASE_URL'],
config_id=os.environ['HAWCX_CONFIG_ID'],
)
# Begin a step-up flow
result = client.start_token(
user_id='user@example.com',
purpose='change_mfa_method',
new_mfa_method='sms_otp', # 'sms_otp' | 'email_otp' | 'totp'
)
# Finalize once the user completes the MFA challenge (receipt from your frontend)
client.consume_receipt(receipt='receipt-from-frontend')
```
---
## Java Backend SDK (Complete API)
### HawcxOauthClient
```java
import com.hawcx.oauth.HawcxOauthClient;
import com.hawcx.oauth.HawcxOauthConfig;
import com.hawcx.oauth.JwtVerifier;
import com.hawcx.oauth.TokenRequest;
HawcxOauthConfig config = new HawcxOauthConfig(System.getenv("HAWCX_BASE_URL"));
HawcxOauthClient client = new HawcxOauthClient(config);
```
### `exchangeCodeForClaims(TokenRequest, VerifyOptions)`
```java
TokenRequest req = new TokenRequest(configId, authCode, codeVerifier);
JwtVerifier.VerifyOptions opts = JwtVerifier.VerifyOptions.builder()
.jwksUrl(config.keysEndpoint())
.audience(System.getenv("HAWCX_CONFIG_ID"))
.issuer(System.getenv("HAWCX_BASE_URL"))
.leewaySeconds(10)
.build();
JsonObject claims = client.exchangeCodeForClaims(req, opts);
String userId = claims.get("sub").getAsString();
```
### `verifyJwt(token, opts)`
```java
JsonObject claims = client.verifyJwt(idToken, opts);
```
### Spring Boot Integration
```java
@RestController
public class AuthController {
private final HawcxOauthClient client;
private final JwtVerifier.VerifyOptions verifyOpts;
private final String configId;
public AuthController(@Value("${hawcx.base-url}") String baseUrl,
@Value("${hawcx.config-id}") String configId) {
this.configId = configId;
HawcxOauthConfig config = new HawcxOauthConfig(baseUrl);
this.client = new HawcxOauthClient(config);
this.verifyOpts = JwtVerifier.VerifyOptions.builder()
.jwksUrl(config.keysEndpoint())
.audience(configId)
.issuer(baseUrl)
.leewaySeconds(10)
.build();
}
public record ExchangeRequest(String authCode, String codeVerifier) {}
@PostMapping("/exchange")
public ResponseEntity exchange(@RequestBody ExchangeRequest body) {
try {
TokenRequest req = new TokenRequest(configId, body.authCode(), body.codeVerifier());
JsonObject claims = client.exchangeCodeForClaims(req, verifyOpts);
return ResponseEntity.ok(Map.of(
"success", true,
"userId", claims.get("sub").getAsString()
));
} catch (Exception e) {
return ResponseEntity.status(401).body(Map.of("error", "Authentication failed"));
}
}
}
```
### Java Step-Up Client (MFA Management)
Java's management surface is `StepUpClient` — `startToken`, `consumeReceipt`,
`getSigninPolicy`, `getMfaEnforcement`, `setMfaEnforcement`. Prefer
`withPrivateKeyJwt` (RFC 7523). A legacy `StepUpClient.fromSecretKey(baseUrl,
"hwx_sk_v1_…", configId)` (ECIES blob) also exists but is deprecated.
```java
import com.hawcx.delegation.StepUpClient;
import com.hawcx.management.StartTokenResponse;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
// Load your Ed25519 OIDC signing key (same one registered in the Admin Console)
String pem = System.getenv("HAWCX_OIDC_PRIVATE_KEY_PEM")
.replaceAll("-----BEGIN PRIVATE KEY-----|-----END PRIVATE KEY-----|\\s", "");
PrivateKey privateKey = KeyFactory.getInstance("Ed25519")
.generatePrivate(new PKCS8EncodedKeySpec(Base64.getDecoder().decode(pem)));
StepUpClient client = StepUpClient.withPrivateKeyJwt(
System.getenv("HAWCX_BASE_URL"),
System.getenv("HAWCX_CONFIG_ID"),
privateKey,
System.getenv("HAWCX_PRIVATE_KEY_KID"),
System.getenv("HAWCX_CLIENT_ID"));
// Begin a step-up flow (mfaMethod: "email_otp" | "sms_otp" | "totp")
StartTokenResponse token = client.startToken(
"user@example.com", "change_mfa_method", "totp");
// Finalize after the user completes the MFA challenge (receipt from your frontend)
client.consumeReceipt("receipt-from-frontend");
```
---
## Android Native SDK (Kotlin)
### Installation
```groovy
// build.gradle
dependencies {
implementation 'com.hawcx:hawcx-android-sdk:4.0.0'
}
```
### Initialize
```kotlin
import com.hawcx.internal.HawcxSDK
class MainApplication : Application() {
companion object {
lateinit var hawcxSdkInstance: HawcxSDK
private set
}
override fun onCreate() {
super.onCreate()
hawcxSdkInstance = HawcxSDK(
context = this.applicationContext,
projectApiKey = "YOUR_CONFIG_ID"
)
}
}
```
### Hawcx Authentication
Hawcx auto-detects new vs returning users. Single entry point — no separate signup/signin.
```kotlin
class AuthManager : AuthV4Callback {
private val sdk = MainApplication.hawcxSdkInstance
fun smartConnect(email: String) {
sdk.authenticateV4(userid = email, callback = this)
}
fun submitOTP(otp: String) {
sdk.submitOtpV4(otp = otp)
}
override fun onOtpRequired() {
// Show OTP input UI
}
override fun onAuthSuccess(accessToken: String?, refreshToken: String?, isLoginFlow: Boolean) {
if (isLoginFlow) {
// Fully authenticated — navigate to home
} else {
// Device registration phase — SDK continues automatically
}
}
override fun onError(errorCode: AuthV4ErrorCode, errorMessage: String) {
// Handle error
}
}
```
### SDK Methods (Android)
- `authenticateV4(userid: String, callback: AuthV4Callback)` — initiate authentication
- `submitOtpV4(otp: String)` — submit OTP when required
- `cancelV4Auth()` — cancel ongoing authentication
### SDK Callbacks (AuthV4Callback)
- `onOtpRequired()` — new user/device needs verification
- `onAuthSuccess(accessToken, refreshToken, isLoginFlow)` — authentication succeeded
- `onError(errorCode, errorMessage)` — error occurred
### Device Session Management (Android)
- `clearSessionTokens(userId)` — standard logout, keeps device trusted (no OTP on next login)
- `clearUserData(userId)` — full device removal, user must re-verify with OTP
- `getLastLoggedInUser()` — returns last authenticated email (for pre-fill)
- `clearLastLoggedInUser()` — clear pre-fill record
### Error Codes (Android AuthV4ErrorCode)
| Code | Description |
|------|-------------|
| `networkError` | Network connectivity issue |
| `invalidInput` | Invalid email format |
| `keychainSaveFailed` | Failed to save to Keystore |
| `clientCryptoError` | Cryptographic operation failed |
| `fingerprintError` | Device fingerprint failed |
| `authInitFailed` | Auth initialization failed |
| `otpVerificationFailed` | Invalid or expired OTP |
| `deviceVerificationFailed` | Device registration verification failed |
| `missingCryptoForLogin` | Device keys not found |
---
## iOS Native SDK (Swift)
### Installation (SPM)
```swift
dependencies: [
.package(url: "https://github.com/hawcx/hawcx_ios_sdk", .upToNextMajor(from: "4.0.2"))
]
```
### Initialize
```swift
import HawcxFramework
let hawcxSDK = HawcxSDK(projectApiKey: "YOUR_CONFIG_ID")
```
### Hawcx Authentication
```swift
class AuthManager: NSObject, AuthV4Callback {
private let sdk = HawcxSDK(projectApiKey: "YOUR_CONFIG_ID")
func smartConnect(email: String) {
sdk.authenticateV4(userid: email, callback: self)
}
func submitOTP(otp: String) {
sdk.submitOtpV4(otp: otp)
}
func onOtpRequired() {
// Show OTP input UI
}
func onAuthSuccess(accessToken: String?, refreshToken: String?, isLoginFlow: Bool) {
if isLoginFlow {
// Fully authenticated
} else {
// Device registration phase
}
}
func onError(errorCode: AuthV4ErrorCode, errorMessage: String) {
// Handle error
}
}
```
### Web Login Approval (iOS)
```swift
// Step 1: Validate PIN from QR code
sdk.webLogin(pin: pin, callback: self) // WebLoginCallback
// Step 2: Approve login
let webToken = UserDefaults.standard.string(forKey: "web_token")!
sdk.webApprove(token: webToken, callback: self)
// Callbacks: onSuccess(), showError(webLoginErrorCode:errorMessage:)
```
### Device Session Management (iOS)
- `clearSessionTokens(forUser: userId)` — logout, keep device trusted
- `clearUserKeychainData(forUser: userId)` — full device removal (destructive)
- `getLastLoggedInUser() -> String` — last authenticated email
- `clearLastLoggedInUser()` — clear pre-fill
### Error Codes (iOS AuthV4ErrorCode)
| Code | Description |
|------|-------------|
| `networkError` | Network issue or timeout |
| `invalidInput` | Invalid email format |
| `keychainSaveFailed` | Failed to save to Keychain |
| `clientCryptoError` | Cryptographic operation failed |
| `fingerprintError` | Device fingerprint failed |
| `otpVerificationFailed` | Invalid or expired OTP |
| `missingCryptoForLogin` | Device keys not found |
| `internalStateError` | SDK state corruption |
### iOS WebLoginErrorCode
| Code | Description |
|------|-------------|
| `invalidPin` | 7-digit PIN invalid or expired |
| `failedApprove` | Approval failed |
| `networkError` | Network issue |
---
## React Native SDK
### Installation
```bash
npm install @hawcx/react-native-sdk@1.1.5
cd ios && pod install # iOS
# Android: add Hawcx Maven repo to settings.gradle (see below)
```
Android Maven setup:
```kts
// android/settings.gradle(.kts)
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://raw.githubusercontent.com/hawcx/hawcx_android_sdk/main/maven")
metadataSources { mavenPom(); artifact() }
}
}
}
```
### Initialize
```tsx
import { initialize, addAuthListener } from '@hawcx/react-native-sdk';
await initialize({
projectApiKey: 'YOUR_CONFIG_ID',
baseUrl: 'https://your-tenant.hawcx-api.hawcx.com',
});
```
### Authentication (React Native)
```tsx
import { useHawcxAuth, storeBackendOAuthTokens } from '@hawcx/react-native-sdk';
function SmartConnectScreen() {
const { state, authenticate, submitOtp, reset } = useHawcxAuth();
const [email, setEmail] = useState('');
const [otp, setOtp] = useState('');
useEffect(() => {
if (state.status === 'authorization_code' && email.trim()) {
exchangeCode(email.trim(), state.payload)
.catch(console.error)
.finally(() => reset());
}
}, [state, email, reset]);
return (