Authentication

The SiteVisit API uses Bearer token authentication. Every request must include an Authorization header carrying a key you generated in the dashboard.

Authorization: Bearer sv_live_e059b3544b7fa4b93c7e26933aeba781

Key format

sv_live_<32 hex chars>   ← real customer data
sv_test_<32 hex chars>   ← parallel sandbox dataset

sv_ is the SiteVisit prefix.
live or test identifies the mode — test keys operate on a parallel sandbox dataset that’s completely separate from your production data. See Test mode below.
The tail is 16 random bytes encoded as 32 lowercase hex characters.

We store only a SHA-256 hash of the tail and the prefix in cleartext (just enough to identify which key is which in the UI). On the wire we compare in constant time.

Generate a key

Sign in to sitevisit.app.
Open Settings → Developers.
Type a name (e.g. production-warehouse, marc-laptop).
Choose Mode → Live for production data, or Mode → Test for the sandbox.
Click Generate key.
Copy the full value immediately — we display it once.

Test mode

Stripe-style — sv_test_* keys operate on a parallel sandbox dataset that’s completely separate from your production data. Properties, site visits, action items, capture tokens, and webhook endpoints created with a test key are tagged isTest: true and never visible to live-mode callers (or vice versa). Test mode is free + unmetered. Test resources don’t count against your plan limits — developers on any tier can build end-to-end without paying.

# List your test-mode properties
curl https://sitevisit.app/api/v1/properties \
  -H "Authorization: Bearer sv_test_..."

# Create a test property
curl -X POST https://sitevisit.app/api/v1/properties \
  -H "Authorization: Bearer sv_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Property"}'

Every response includes isTest: true|false so you can confirm at a glance which dataset you hit.

Webhooks in test mode

Webhook endpoints have their own mode (live or test, set when you create the endpoint in Settings → Developers → Webhooks). Test-mode endpoints only receive events triggered by sv_test_* keys; live endpoints only receive events from sv_live_* keys. Test traffic never crosses into live receivers. Every webhook payload includes a top-level livemode boolean so receivers can branch without parsing the resource itself:

{
  "id": "evt_abc123",
  "event_type": "property.created",
  "livemode": false,           // ← true for sv_live_, false for sv_test_
  "created_at": "2026-06-06T...",
  "data": { "property": { /* PropertyDto */ } }
}

Once you close the reveal panel, the full secret is gone forever. We keep only a hash. If you lose it, revoke and re-issue.

Rotate a key

There’s no rotation endpoint — generate a new key, swap it into your secret store, then revoke the old one once traffic has moved over. This pattern keeps you in control of the cutover window.

Revoke a key

In Settings → Developers, click Revoke next to the key. Revoked keys reject all subsequent requests with 401 invalid_api_key. Revocation is immediate; we do not honor a grace period.

Scopes

Every key has full read + write access to the account that issued it. The only access boundary today is the mode (live vs test) — test keys can never reach into live data or vice versa.

Where to store keys

API keys are secrets. Don’t:

Commit them to a repository.
Embed them in mobile apps or frontend JavaScript.
Share them across teams in chat or email.

Instead, store them in your platform’s secret manager (Vercel envs, AWS Secrets Manager, 1Password, etc.) and inject at runtime.

Errors

Status	Code	Meaning
`401`	`missing_api_key`	No `Authorization` header was sent.
`401`	`invalid_api_key`	Header present but the key doesn’t match a live, non-revoked key.
`403`	`forbidden`	The key is valid but isn’t allowed to access this resource.

See the Errors page for the full envelope shape and the docs_url link pattern.

Get started

Concepts

Account

AI integration

Webhooks

Key format

Generate a key

Test mode

Webhooks in test mode

Rotate a key

Revoke a key

Scopes

Where to store keys

Errors

​Key format

​Generate a key

​Test mode

​Webhooks in test mode

​Rotate a key

​Revoke a key

​Scopes

​Where to store keys

​Errors

Key format

Generate a key

Test mode

Webhooks in test mode

Rotate a key

Revoke a key

Scopes

Where to store keys

Errors