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';
const oauth = new HawcxOAuth({
configId: process.env.HAWCX_CONFIG_ID!,
baseUrl: process.env.HAWCX_BASE_URL, // optional, default: https://api.hawcx.com
jwksCacheTtl: 60 * 60 * 1000, // optional, default: 1 hour
timeout: 10_000 // optional, default: 10000ms
});
```
### `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);
```
### `clearCache()` — clear JWKS cache
```typescript
oauth.clearCache();
```
### Error Types
```typescript
import { TokenExchangeError, TokenVerificationError } from '@hawcx/oauth-client';
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 = new HawcxOAuth({ configId: process.env.HAWCX_CONFIG_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 = new HawcxOAuth({ configId: process.env.HAWCX_CONFIG_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' });
}
});
```
### Delegation Client (MFA Management)
```typescript
import { DelegationClient, MfaMethod } from '@hawcx/oauth-client';
// Option 1: From secret key blob
const client = DelegationClient.fromSecretKey({
secretKey: process.env.HAWCX_SECRET_KEY!,
baseUrl: 'https://api.hawcx.com',
apiKey: process.env.HAWCX_CONFIG_ID
});
// Option 2: From individual keys
const client = DelegationClient.fromKeys({
spSigningKey: process.env.SP_ED25519_PRIVATE_KEY_PEM!,
spEncryptionKey: process.env.SP_X25519_PRIVATE_KEY_PEM!,
idpVerifyKey: process.env.IDP_ED25519_PUBLIC_KEY_PEM!,
idpEncryptionKey: process.env.IDP_X25519_PUBLIC_KEY_PEM!,
spKid: process.env.SP_KEY_ID!,
idpKid: process.env.IDP_KEY_ID!,
baseUrl: 'https://api.hawcx.com',
apiKey: process.env.HAWCX_CONFIG_ID
});
// Initiate MFA setup
const result = await client.mfa.initiate({
userId: 'user@example.com',
mfaMethod: MfaMethod.SMS, // or MfaMethod.EMAIL, MfaMethod.TOTP
phoneNumber: '+15551234567'
});
// Verify OTP
await client.mfa.verify({
userId: 'user@example.com',
sessionId: result.session_id,
otp: '123456'
});
// User management
const creds = await client.users.getCredentials('user@example.com');
// Device management
const devices = await client.devices.list('user@example.com');
await client.devices.revoke({ userId: 'user@example.com', deviceId: 'h2index' });
```
---
## Python Backend SDK — Complete API
### HawcxOAuth
```python
from hawcx_oauth_client import HawcxOAuth
import os
oauth = HawcxOAuth(
config_id=os.getenv('HAWCX_CONFIG_ID'),
base_url=os.getenv('HAWCX_BASE_URL') # optional
)
```
### `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(config_id=os.getenv('HAWCX_CONFIG_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(config_id=os.getenv('HAWCX_CONFIG_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(config_id=os.getenv('HAWCX_CONFIG_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 Delegation Client (MFA Management)
```python
from hawcx_oauth_client.delegation import HawcxDelegationClient, MfaMethod
import os
client = HawcxDelegationClient.from_keys(
sp_signing_key=os.getenv('SP_ED25519_PRIVATE_KEY_PEM'),
sp_encryption_key=os.getenv('SP_X25519_PRIVATE_KEY_PEM'),
idp_verify_key=os.getenv('IDP_ED25519_PUBLIC_KEY_PEM'),
idp_encryption_key=os.getenv('IDP_X25519_PUBLIC_KEY_PEM'),
base_url=os.getenv('HAWCX_BASE_URL') or 'https://api.hawcx.com',
sp_id=os.getenv('OAUTH_CLIENT_ID')
)
# Initiate MFA
result = client.initiate_mfa_change(
userid='user@example.com',
mfa_method=MfaMethod.SMS,
phone_number='+15551234567'
)
# Verify
client.verify_mfa_change(
userid='user@example.com',
session_id=result['session_id'],
otp='123456'
)
# Get user credentials
creds = client.get_user_credentials('user@example.com')
```
---
## 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 Delegation Client (MFA Management)
```java
import com.hawcx.delegation.DelegationClient;
import com.hawcx.delegation.MfaMethod;
DelegationClient client = DelegationClient.fromSecretKey(
System.getenv("HAWCX_BASE_URL"),
System.getenv("HAWCX_SECRET_KEY"), // hwx_sk_v1_...
System.getenv("HAWCX_CONFIG_ID")
);
// Initiate MFA
JsonObject result = client.mfa.initiate(
"user@example.com",
MfaMethod.SMS,
"+15551234567",
null
);
// Verify
client.mfa.verify("user@example.com",
result.get("session_id").getAsString(),
"123456");
// User credentials and suggested-MFA preference
JsonObject creds = client.users.getCredentials("user@example.com");
client.users.setSuggestedMfa("user@example.com", "always");
// Device management
JsonObject devices = client.devices.list("user@example.com");
client.devices.revoke("user@example.com", "h2index");
```
---
## 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.0"))
]
```
### 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 (