Authentication

VH3 Connect exposes two REST API groups for server-to-server integration, plus a User Auth API for interactive applications. You receive a single API key during onboarding; how you send it depends on which API you call.

Two API surfaces

API	Base URL	Auth	Tenant scope
VH3 AI Intelligence	`https://api.vh3connect.io/api:kP8T1CK7`	`company_id` + `api_key` (body or query)	Explicit `company_id` on every request
BigChange API	`https://api.vh3connect.io/api:YdihQNr3`	`X-API-Key` header only	Resolved from the API key

The API key is the same credential for both groups. Intelligence endpoints require your company ID in addition; BigChange proxy endpoints do not.

VH3 AI Intelligence, quick reference

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/search/outcomes" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "query_text": "boiler fault",
    "limit": 5
  }'

BigChange API, quick reference

curl -X POST "https://api.vh3connect.io/api:YdihQNr3/jobs/list" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "pageNumber": 1,
    "pageSize": 20
  }'

User Auth (interactive apps)

Login with email and password on api:lBQnyyZL; use the returned JWT as Authorization: Bearer. No API key in client code. See User Authentication below.

VH3 AI Intelligence authentication

All intelligence-layer endpoints require company ID and API key on every request.

Field	Type	Description
`company_id`	string	Your tenant identifier, identifies your organisation
`api_key`	string	Your tenant API key, authenticates the request

These are passed on every request. For POST endpoints, they go in the JSON body. For GET endpoints, they go as query parameters.

POST example (most endpoints)

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/search/outcomes" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "query_text": "boiler intermittent fault",
    "limit": 5
  }'

GET example (feeds, detail lookups)

curl -G "https://api.vh3connect.io/api:kP8T1CK7/jobs/feed" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "page_size=20"

Requests missing company_id or api_key will receive a 400 response with a Missing param error.

BigChange API authentication

BigChange proxy endpoints use the same API key as the intelligence layer, passed only in the X-API-Key HTTP header. Do not send company_id on these requests, the gateway resolves your tenant and BigChange session from the key.

curl -G "https://api.vh3connect.io/api:YdihQNr3/contacts/contact" \
  -H "X-API-Key: your-api-key" \
  --data-urlencode "contactId=12345"

Header	Required	Description
`X-API-Key`	Yes	Your tenant API key
`Content-Type`	Yes (POST)	`application/json`

Missing or invalid X-API-Key returns 401 Unauthorised. Do not put the API key in the JSON body for BigChange endpoints.

Full endpoint list: BigChange API reference.

User Authentication

For interactive applications, custom dashboards, customer portals, embedded tools, VH3 provides per-user authentication with JWT tokens. Users log in with email and password only. The tenant is resolved server-side from their account. After login, every call from the client uses the JWT, no API key is ever involved in client-side code.

How it works

Authenticate a user with email and password. The user’s tenant is resolved server-side, no API key is required from the client.

curl -X POST "https://api.vh3connect.io/api:lBQnyyZL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'

Response:

{
  "authToken": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2Q0..."
}

Store the authToken in your application (e.g. httpOnly cookie in production). All subsequent requests use Authorization: Bearer <token>, no API key is ever sent from the client.

Token refresh

Refresh an expiring token before it expires. Requires a valid Bearer token.

curl -X POST "https://api.vh3connect.io/api:lBQnyyZL/auth/refresh" \
  -H "Authorization: Bearer eyJhbGciOi..."

Response:

{
  "authToken": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2Q0..."
}

Get current user

Retrieve the profile of the authenticated user.

curl "https://api.vh3connect.io/api:lBQnyyZL/auth/me" \
  -H "Authorization: Bearer eyJhbGciOi..."

Response:

{
  "id": 42,
  "first_name": "Jane",
  "last_name": "Smith",
  "company_id": "abc-123-def",
  "email": "jane@example.com",
  "role": "admin",
  "phone": null,
  "profile_picture": { "url": null },
  "_company": {
    "id": "abc-123-def",
    "name": "Acme Field Services"
  }
}

Token shape

JWT tokens issued by the User Auth API:

Claim	Description
`id`	User ID (integer)
`company`	Company ID (UUID), the tenant the user belongs to
`iss`	Token issuer
`exp`	Expiry timestamp (24 hours from issue)

The same token works across both the User Auth endpoints and the main VH3 data API when configured with Bearer auth middleware.

Using the token in your application

The example below stores the token in localStorage and calls the VH3 API directly from the browser. This is for local development and testing only. In any app that real users can access — including internal tools, partner portals, and MVPs — the token must be stored in an httpOnly secure cookie and all VH3 API calls must originate from your backend server. Calling the VH3 API from browser code means anyone who can open the browser network tab can replay those calls directly against your organisation’s data.

// Development only — do not use this pattern in any user-facing application
const token = localStorage.getItem('vh3_token');

const response = await fetch('https://api.vh3connect.io/api:kP8T1CK7/connie/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({
    message: 'How many jobs were completed this week?',
  }),
});

In production: store the authToken from /auth/login in an httpOnly secure cookie on your backend. On every request, your server reads the cookie, calls GET /auth/me to validate the token and retrieve the user’s company, then makes the VH3 API call server-side. The browser never sees the token directly and never calls the VH3 API. See Deploying secure apps for the full frontend/backend pattern.

User Management

VH3 provides two ways to manage users depending on your integration type:

Use case	Endpoint set	Auth
Back-end / server-to-server: cron jobs, admin scripts, integrations	`GET /users/list`, `POST /users/invite`, `PUT /users/{id}/role`, `DELETE /users/{id}` on `api:kP8T1CK7`	`company_id` + `api_key` (server-side only, never sent from a browser)
Interactive front-end: custom dashboards, portals, embedded tools	`POST /users/invite`, `GET /users/list`, `DELETE /users/{id}` on `api:lBQnyyZL`	Bearer JWT, no API key in client code

Never call the api:kP8T1CK7 user management endpoints from a browser or mobile app, doing so exposes your API key in client-side code. Use the JWT-authenticated equivalents on api:lBQnyyZL instead.

The section below covers the JWT-based variants for interactive applications. For the server-side company_id + api_key variants, see the Users API reference. Admin users can manage team members via the User Auth API. All user management endpoints require a valid Bearer token from a user with the admin or developer role.

Invite a user

Send an invitation to a new user. Returns an invitation token (valid for 7 days).

curl -X POST "https://api.vh3connect.io/api:lBQnyyZL/users/invite" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "role": "standard",
    "first_name": "John",
    "last_name": "Doe"
  }'

Response:

{
  "email": "newuser@example.com",
  "role": "standard",
  "invite_token": "eyJhbGciOi...",
  "expires_in": 604800
}

Parameter	Type	Required	Description
`email`	email	Yes	Email address to invite
`role`	string	No	Role to assign: `admin`, `manager`, `standard`, `engineer`. Defaults to `standard`
`first_name`	string	No	First name of the invited user
`last_name`	string	No	Last name of the invited user

List users

List all active users in the authenticated user’s company.

curl "https://api.vh3connect.io/api:lBQnyyZL/users/list?page=1&per_page=25" \
  -H "Authorization: Bearer eyJhbGciOi..."

Response:

{
  "items": [
    {
      "id": 42,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "role": "admin",
      "phone": null,
      "profile_picture": { "url": null },
      "email_verified": true
    }
  ],
  "curPage": 1,
  "nextPage": null,
  "prevPage": null
}

Delete a user

Soft-delete a user (sets is_archived to true). Cannot delete your own account.

curl -X DELETE "https://api.vh3connect.io/api:lBQnyyZL/users/42" \
  -H "Authorization: Bearer eyJhbGciOi..."

Response:

{
  "success": true,
  "user_id": 42
}

Roles

Role	Permissions
`admin`	Full access, can invite, list, and delete users
`developer`	Same as admin
`manager`	Standard data access, no user management
`standard`	Standard data access, no user management
`engineer`	Standard data access, no user management

Your credentials

During onboarding you receive:

Company ID: your unique tenant identifier
API Key: your tenant authentication key

Both are provided by your account manager or visible in your VH3 Connect dashboard settings.

Error responses

All errors follow a consistent format:

{
  "code": "ERROR_CODE_INPUT_ERROR",
  "message": "Missing param: company_id",
  "payload": {
    "param": "company_id"
  }
}

Status code	Meaning
`400`	Bad request, missing or invalid parameters
`401`	Unauthorised, invalid API key or expired token
`403`	Forbidden, insufficient role permissions
`404`	Not found, resource does not exist for your tenant
`409`	Conflict, a task is already running for this resource
`422`	Validation error, request understood but semantically invalid
`429`	Rate limited, too many requests
`500`	Server error, contact support

Security

Your API key is tenant-scoped and grants access to your organisation’s data only. Treat it like a password, store it in server-side environment variables only. Never include it in client-side code, browser bundles, or mobile apps. For interactive front-ends, use User Authentication (JWT), users log in with email and password only, and the API key is never involved.

All requests must use HTTPS
API keys can be rotated on request via your account manager
JWT tokens expire after 24 hours, use the refresh endpoint to obtain a new token before expiry
Store JWT tokens in httpOnly secure cookies in production. localStorage is acceptable for local development only — never in user-facing apps

​Authentication

​Two API surfaces

​VH3 AI Intelligence, quick reference

​BigChange API, quick reference

​User Auth (interactive apps)

​VH3 AI Intelligence authentication

​POST example (most endpoints)

​GET example (feeds, detail lookups)

​BigChange API authentication

​User Authentication

​How it works

​Login

​Token refresh

​Get current user

​Token shape

​Using the token in your application

​User Management

​Invite a user

​List users

​Delete a user

​Roles

​Your credentials

​Error responses

​Security

Authentication

Two API surfaces

VH3 AI Intelligence, quick reference

BigChange API, quick reference

User Auth (interactive apps)

VH3 AI Intelligence authentication

POST example (most endpoints)

GET example (feeds, detail lookups)

BigChange API authentication

User Authentication

How it works

Login

Token refresh

Get current user

Token shape

Using the token in your application

User Management

Invite a user

List users

Delete a user

Roles

Your credentials

Error responses

Security