Get started

Authentication

Both the PatientNow Essentials (PNE) and VISH APIs require two things on every request: your gateway API key (an apikey parameter) and HTTP Basic user credentials. There are no anonymous endpoints.

The auth scheme

Every request carries two credentials:

1. An apikey — your gateway key, identifying your integration to the API gateway. Send it on every call.
2. HTTP Basic user credentials — a username and password, Base64-encoded, identifying the acting user. The API validates them against an active user on each call; there is no login step or bearer token to exchange.

• Both are checked per request (the API is stateless).
• Authenticated calls run with that user's permissions.
• A missing/invalid apikey or bad user credentials return 401 Unauthorized.

Your gateway key (apikey)

The apikey is issued to your integration and is required on every request, in addition to the Basic user credentials below. Pass it as an apikey query-string parameter:

# apikey on the query string + Basic user credentials in the header:
curl "https://api.envisiongo.com/api/v1/status?apikey=YOUR_API_KEY" \
  -u "USERNAME:PASSWORD"

const token = btoa("USERNAME:PASSWORD"); // Node: Buffer.from(...).toString("base64")
const res = await fetch(`${base}/status?apikey=YOUR_API_KEY`, {
  headers: { Authorization: `Basic ${token}` },
});

from requests.auth import HTTPBasicAuth
res = requests.get(
    f"{base}/status",
    params={"apikey": "YOUR_API_KEY"},
    auth=HTTPBasicAuth("USERNAME", "PASSWORD"),
)

// Append apikey to the query string; Basic header set on the client (below).
var res = await http.GetAsync("status?apikey=YOUR_API_KEY");

User credentials — Authorization header (recommended)

Send the Base64 of username:password in the standard Basic Authorization header. Most HTTP clients build this for you when you supply a username and password.

# Let cURL build the header (apikey still required on the query string):
curl "https://api.envisiongo.com/api/v1/status?apikey=YOUR_API_KEY" \
  -u "USERNAME:PASSWORD"

# Equivalent explicit header:
curl "https://api.envisiongo.com/api/v1/status?apikey=YOUR_API_KEY" \
  -H "Authorization: Basic $(printf 'USERNAME:PASSWORD' | base64)"

const token = btoa("USERNAME:PASSWORD"); // Node: Buffer.from(...).toString("base64")
const res = await fetch(`${base}/status?apikey=YOUR_API_KEY`, {
  headers: { Authorization: `Basic ${token}` },
});

from requests.auth import HTTPBasicAuth
res = requests.get(
    f"{base}/status",
    params={"apikey": "YOUR_API_KEY"},
    auth=HTTPBasicAuth("USERNAME", "PASSWORD"),
)

var token = Convert.ToBase64String(Encoding.UTF8.GetBytes("USERNAME:PASSWORD"));
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", token);
var res = await http.GetAsync("status?apikey=YOUR_API_KEY");

Header-less user token (api_key)

Where you genuinely can't set an Authorization header, the Base64 username:password token may instead be passed as an api_key query parameter (note the underscore — this is distinct from the gateway apikey above). Its value is identical to what you'd put after Basic in the header. The gateway apikey is still required alongside it.

curl "https://api.envisiongo.com/api/v1/status?apikey=YOUR_API_KEY&api_key=BASE64_OF_USER_COLON_PASS"

Base URL

Both APIs share a single base URL — the host plus the versioned api/v1 path:

https://api.envisiongo.com/api/v1

So a typical full URL is https://api.envisiongo.com/api/v1/customers. There is no per-customer path prefix — your gateway apikey (not the URL) determines which API and account a request resolves to.

Both APIs share the host api.envisiongo.com; your gateway apikey determines which one your account reaches. VISH has no status endpoint, so its cleanest connectivity check is GET /api/v1/companies — see the VISH quickstart.

Common 401 causes

A 401 Unauthorized means the request was rejected before your data was touched. Work through these in order:

Pre-flight checklist

• ✅ Calling over https://
• ✅ Base URL ends in /api/v1
• ✅ Gateway apikey (no underscore) on the query string of every request
• ✅ Authorization: Basic <base64(user:pass)> present on every request
• ✅ Token is Base64 of user:pass with a single colon, encoded once
• ✅ The user is active and authorized for API access
• ✅ Using a dedicated API user, with the key and credentials kept out of source control