Authentication — VenHub Developer Docs

Authentication Methods

Method	Header	Description
API Key	`X-API-Key: vh_...`	Third-party API key authentication
Firebase	`Authorization: Bearer <token>`	Firebase user authentication

API Key Authentication

API keys are long-lived credentials prefixed with vh_. They are ideal for backend services, cron jobs, and third-party integrations where a human user is not present.

Where keys come from: TINA & operators

API keys are generated in TINA, the VenHub dashboard — there's no endpoint for creating one programmatically. Every VenHub partner gets their own TINA login.

🔑

Running hubs on behalf of your own customers? You don't have to generate and hand out keys yourself. Add that customer as an operator on the hub in TINA, and they get their own TINA access to generate and manage their own scoped API key — they can operate and run the hub directly, without going through you for every key.

Usage

Include your API key in the X-API-Key header on every request:

cURL

curl -X GET \
  "https://tina-api.venhub.com/api/v1/owners/hub_inventory/?hub_id=123" \
  --header "X-API-Key: vh_abc123your_key_here"

Key Format

All API keys follow the pattern vh_ followed by a random alphanumeric string. Keys are case-sensitive.

Permission Scopes

API keys are issued with one or more scopes that control which endpoints they can access. Follow the principle of least privilege — only grant the scopes your integration actually needs.

Scope	Permission	Endpoints
`inventory:read`	Read inventory data	GET /hub_inventory GET /hubs/product
`inventory:write`	Modify inventory data	PUT /hubs/product/{product_id}/update_quantity PUT /product/{product_id}/update_price PUT /product/{product_id}/update_purchase_price PUT /product/{product_id}/update_upc
`orders:read`	View orders	GET /hubs/all_orders_paginated
`orders:write`	Process refunds	POST /orders/{order_id}/refund POST /items/{id}/refund
`analytics:read`	View sales analytics	All GET /analytics endpoints
`hubs:read`	View hub info & status	GET /hubs, /hub_ids, /get_hub_info, /hub_layout, /get_hub_health, /get_door_status, /fridge_door_cabinet_map
`hubs:write`	Control hub access	POST /request_door_open
`controls:read`	Read hardware status	GET /controls/get_bin_status
`controls:write`	Send hardware commands	All POST /controls endpoints
`maintenance:read`	View maintenance reports	GET /maintenance/reports GET /maintenance/reports/{id}
`maintenance:write`	Create maintenance reports	POST /maintenance/reports
`promotions:read`	View banners & deals	GET /owner/banners, GET /deals/*
`promotions:write`	Manage banners & deals	POST/PUT/DELETE banners & deals

Key Expiration

API keys can be set with an optional expiration date. An expired key returns a 401 api_key_expired error. Keys without an expiration remain valid until revoked.

Firebase Authentication

Firebase user authentication is used for requests made on behalf of a signed-in VenHub user.

Usage

Include the Firebase ID token in the Authorization header on every request:

cURL

curl -X GET \
  "https://tina-api.venhub.com/api/v1/owners/hub_inventory/?hub_id=123" \
  --header "Authorization: Bearer <token>"

Authentication Errors

Error Code	HTTP Status	Description
invalid_api_key	401	API key is missing, malformed, or has been revoked
api_key_expired	401	API key has passed its expiration date
scope_missing	403	API key does not have the required permission scope for this endpoint
hub_access_denied	403	API key is valid but does not have access to the requested hub