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:

  1. SDK Approach: Use the official HVT SDKs.
  2. 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):

javascript
import { HVTClient } from '@hvt/sdk';

const client = new HVTClient({
  baseUrl: 'https://api.hvts.app',
  apiKey: 'hvt_test_your_project_key',
  credentials: 'omit'
});

await client.request('/api/v1/auth/runtime/register/', {
  method: 'POST',
  auth: 'apiKey',
  body: {
    email: '[email protected]',
    password1: 'Strongpass123!',
    password2: 'Strongpass123!'
  }
});

const session = await client.auth.runtimeLogin({
  email: '[email protected]',
  password: 'Strongpass123!'
});

(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.

Critical Requirement
All requests from your application on behalf of end-users must target the 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:

http
X-API-Key: <YOUR_PROJECT_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.

Do not use the site origin as the API origin
If you are using the managed service, send runtime requests to https://api.hvts.app, not https://hvts.app.
Browser CORS policy
Browser-based runtime auth is allowed from localhost automatically when you use a 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/
json
{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "first_name": "Jane",
  "last_name": "Doe"
}

Verify Email

POST /runtime/register/verify-email/
json
{
  "key": "<verification_key>"
}

Resend Verification Email

POST /runtime/register/resend-email/
json
{
  "email": "[email protected]"
}

Authentication

Login

POST /runtime/login/
json
{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}

*Response contains access and refresh tokens.*

Refresh JWT Token

POST /token/refresh/
json
{
  "refresh": "<your_refresh_token>"
}

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/
json
{
  "email": "[email protected]"
}

Validate Reset Token

POST /runtime/password/reset/validate/
json
{
  "uid": "<uidb64>",
  "token": "<token>"
}

Confirm Password Reset

POST /runtime/password/reset/confirm/<uidb64>/<token>/
json
{
  "new_password": "NewSecurePassword123!"
}

Social Authentication (OAuth)

List Configured Providers

GET /runtime/social/providers/

Google Login

POST /runtime/social/google/
json
{
  "access_token": "<google_access_token>"
}

GitHub Login

POST /runtime/social/github/
json
{
  "code": "<github_oauth_code>"
}

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.

  1. App sends: Authorization: Bearer <HVT_ACCESS_TOKEN>
  2. Decode JWT header/payload on your server (using standard libraries like PyJWT, jsonwebtoken).
  3. Validate expiration (exp).
  4. Validate signature against the project's generated signing key.
  5. Extract standard HVT payload claims:
    • user_id: Identifies the user.
    • org_id: Enforces organization bounds.
    • project_id: Enforces project bounds.