HVT Integration Guide
HVT operates on two planes: the Control Plane (for your developer administration) and the Runtime Plane (for end-user authentication). This document focuses entirely on integrating your application with the Runtime Plane.
Two approaches exist for integration:
- SDK Approach: Use the official HVT SDKs.
- Non-SDK Approach (REST API): Make direct HTTP requests to the Runtime endpoints.
1. SDK Approach
The officially supported SDKs abstract away the REST API calls and handle token storage automatically.
Available SDKs:
- TypeScript/JavaScript (Platform/Frontend) - Located in
sdk/typescript/
Basic Usage (Conceptual):
(Reference your specific language documentation in the SDK folder for full methods).
2. Non-SDK Approach (Direct REST Integration)
If your language or framework does not have an official SDK, use raw HTTP requests.
runtime/ prefixed endpoints. "Normal" endpoints (like /api/v1/auth/login/) are strictly for the Control Plane (Dashboard) users.Required Header
Every request to the Runtime endpoints requires your project's API key:
Complete Runtime URL Reference
Managed service base URL: https://api.hvts.app/api/v1/auth. Local development base URL: http://localhost:8000/api/v1/auth.
https://api.hvts.app, not https://hvts.app.hvt_test_* key. Live keys require the browser origin to match the project's runtime frontend URL or configured allowed origins.Registration & Verification
Register User
POST /runtime/register/Verify Email
POST /runtime/register/verify-email/Resend Verification Email
POST /runtime/register/resend-email/Authentication
Login
POST /runtime/login/*Response contains access and refresh tokens.*
Refresh JWT Token
POST /token/refresh/To bootstrap an existing runtime session, use /api/v1/auth/runtime/me/ and the refresh-retry flow described in Bootstrap the current runtime session.
Password Management
Request Password Reset
POST /runtime/password/reset/Validate Reset Token
POST /runtime/password/reset/validate/Confirm Password Reset
POST /runtime/password/reset/confirm/<uidb64>/<token>/Social Authentication (OAuth)
List Configured Providers
GET /runtime/social/providers/Google Login
POST /runtime/social/google/GitHub Login
POST /runtime/social/github/Validating Tokens on Your Backend
When acting purely via the REST API, you must validate the Bearer tokens (JWTs) presented to your backend by your frontend.
- App sends:
Authorization: Bearer <HVT_ACCESS_TOKEN> - Decode JWT header/payload on your server (using standard libraries like PyJWT, jsonwebtoken).
- Validate expiration (
exp). - Validate signature against the project's generated signing key.
- Extract standard HVT payload claims:
user_id: Identifies the user.org_id: Enforces organization bounds.project_id: Enforces project bounds.