API/Endpoint Documentation

Endpoint Documentation

This page describes the available **Verofy API endpoints**, grouped by category.

Categories

• Miscellaneous Endpoints
• Reference Endpoints

---

Miscellaneous Endpoints

Health Check (MISC)

Check whether the API is accessible, or if a particular version of the API is available.

There are two variants of this endpoint:

• **Global Health Check** — verifies the API service as a whole.
• **Version Health Check** — verifies a specific API version.

Returns:

• **200: OK** — the service or version is available.
• **404: Not Found** — the requested service is unavailable.

Ex. 1: Service Health Check

import requests

response = requests.get("https://www.example.com/health-check")
print(response.status_code)   # 200 expected
print(response.text)          # {"api_service": "OK"} expected

Ex. 2: Version Health Check

import requests

response = requests.get("https://www.example.com/v1/health-check")
print(response.status_code)   # 200 expected
print(response.text)          # {"api_v1": "OK"} expected

---

Access Check (MISC)

Check whether authentication has been successful. Accepts either an **access-token** or an **API key**.

Returns:

• **200: OK** — authentication successful
• **401: Unauthorized** — authentication failed

Ex. 3: Failed Access Check

import requests

response = requests.get("https://www.example.com/v1/access-check")
print(response.status_code)   # 401 expected

Ex. 4: Successful Access Check

import requests

headers = {
    "Authorization": "Bearer n20usc92gb2_not_a_real_access_token_1v51r8jmrtfc"
}
response = requests.get(
    "https://www.example.com/v1/references/MapSegmentType",
    headers=headers
)

print(response.status_code)   # 200 expected
print(response.text)          # {"api_v1_access": "OK"} expected

---

Login (MISC)

Provide **user credentials** to retrieve a new **refresh-token**. Intended for user-facing clients.

⚠️ **Never store raw user credentials in a client app** — always prompt the user on each login.

Returns:

• A **refresh-token** if credentials are valid
• **401: Unauthorized** otherwise

Do not send credentials without HTTPS!

Ex. 5: Get Refresh-Token with Login

import requests
import getpass

# Don't hard-code or store user credentials! Always ask the user.
ident = {
    "email": getpass.getuser(),
    "password": getpass.getpass()
}

response = requests.post("https://www.example.com/v1/login", json=ident)

print(response.status_code)   # 200 expected
print(response.text)
# {
#   "username": "example@example.com",
#   "first-name": "John",
#   "last-name": "Doe",
#   "refresh-token": "tq290v0190n1oe290_not_a_real_refresh_token_2901bg02g81"
# } expected

---

Refresh Token (MISC)

Exchange a **refresh-token** for a **new refresh-token** and a **fresh access-token**.

Intended for user-facing clients. Clients should store both tokens for later use.

Notes:

• Refresh-tokens can be used only **once**
• Once used, they are **invalidated**
• Always store the **new** refresh-token from the response

Returns:

• **200: OK** — new tokens issued
• **401: Unauthorized** — invalid or expired refresh-token

Ex. 6: Get Access-Token with Refresh-Token

import requests

# Use the "login" endpoint first to obtain a refresh-token
headers = {
    "Authorization": "Bearer tq290v0190n1oe290_not_a_real_refresh_token_2901bg02g81"
}

response = requests.get("https://www.example.com/v1/refresh-access", headers=headers)
print(response.status_code)   # 200 expected
print(response.text)
# {
#   "username": "example@example.com",
#   "access-token": "n20usc92gb2_not_a_real_access_token_1v51r8jmrtfc",
#   "refresh-token": "8b1w1sx5gfwgwg_new_refresh_token_qn2n7ed2f22bn5ed"
# } expected

---

Settings

The Settings endpoints allow clients to read configuration values stored in the system’s internal setting table. Sensitive items (such as overwatch.password) are automatically excluded.

List Setting Keys

Return the list of available setting names.

GET {api_url}/{version}/setting/keys

Example:

GET https://api.veronetworks.com/v1/setting/keys

Response:

[
"general.document_tags",
"overwatch.username",
"general.google_maps_api_key",
"security.mfa_enabled"
]

Get Setting Record

Retrieve the full definition of a setting.

GET {api_url}/{version}/setting/get?name={settingName}

Example:

GET https://api.veronetworks.com/v1/setting/get?name=security.mfa_enabled

Response:

{
"id": 8,
"name": "security.mfa_enabled",
"label": "MFA Enabled",
"value": "0",
"defaultValue": null,
"type": "bool",
"category": "Security",
"description": "Activating MFA will prompt a code...",
"readOnly": 0,
"updatedAt": "2025-10-22 02:22:12"
}

Reference Endpoints

References (VIEW)

Retrieve the specified **complete collection of reference models** as a single resource.

Optional parameter:

• `hash` — if supplied, the server compares it to its own hash for the collection.

 * If hashes differ → returns the collection.
 * If hashes match → returns an empty response.

• If the `hash` parameter is omitted → the full collection is returned.

If a ref-type is invalid or removed on the server:

• **410: Gone** — client should remove local copies and stop requesting that ref-type.

Returns:

• The collection as a resource (if available)
• **410: Gone** if the ref-type no longer exists
• **401: Unauthorized** if access is denied

---

Next: → API/Endpoints: Models