Authentication and permissions

Each operation declares its accepted authentication. Service integrations use Authorization: Bearer …. User sessions use the eoi_session cookie, and writes also carry X-CSRF-Token. Edge appliance protocol requests use device or enrollment credentials.

Use a service token

Ask your administrator for a scoped service token. Enter it in a Bash terminal using a hidden prompt.

read -rsp "EyesOnIt service token: " EOI_SERVICE_TOKEN
printf '\n'
export EOI_SERVICE_TOKEN

Send it with each request.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${EOI_SERVICE_TOKEN}" \
  "${EOI_API_BASE_URL}/auth/principal"

Check the returned kind and capabilities. The initial camera examples require monitor:read. Camera configuration and lifecycle workflows also need their operation-specific capabilities and resource authority.

Service-token administration currently exposes listing and revocation. Your administrator supplies issuance through the server’s administration tooling.

Use a user session

Use a user account authorized for the task. The following example creates a private temporary directory for the cookie jar and session response. Enter a current MFA code if your account requires one. Keep this terminal open for subsequent session requests.

export EOI_SESSION_DIR="$(mktemp -d)"
chmod 700 "$EOI_SESSION_DIR"
export EOI_COOKIE_JAR="$EOI_SESSION_DIR/cookies.txt"
read -rp "Username: " EOI_USERNAME
read -rsp "Password: " EOI_PASSWORD
printf '\n'
read -rp "MFA code (leave empty if unused): " EOI_TOTP_CODE
export EOI_USERNAME EOI_PASSWORD EOI_TOTP_CODE

python3 - <<'JSON' | curl --fail-with-body --silent --show-error \
  --cookie-jar "$EOI_COOKIE_JAR" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  "${EOI_API_BASE_URL}/auth/login" > "$EOI_SESSION_DIR/login.json"
import json, os
body = {"username": os.environ["EOI_USERNAME"], "password": os.environ["EOI_PASSWORD"]}
if os.environ["EOI_TOTP_CODE"]:
    body["totpCode"] = os.environ["EOI_TOTP_CODE"]
print(json.dumps(body))
JSON
unset EOI_PASSWORD EOI_TOTP_CODE

After a successful login, load the CSRF token and session ID from the response.

export EOI_CSRF_TOKEN="$(python3 -c 'import json,os; print(json.load(open(os.environ["EOI_SESSION_DIR"]+"/login.json"))["csrfToken"])')"
export EOI_SESSION_ID="$(python3 -c 'import json,os; print(json.load(open(os.environ["EOI_SESSION_DIR"]+"/login.json"))["principal"]["sessionId"])')"

Read the current principal with the cookie jar.

curl --fail-with-body --silent --show-error \
  --cookie "$EOI_COOKIE_JAR" \
  --header "X-EyesOnIt-Session-Id: ${EOI_SESSION_ID}" \
  "${EOI_API_BASE_URL}/auth/principal"

For user-session writes, replace a reference template’s bearer header with --cookie "$EOI_COOKIE_JAR", --header "X-EyesOnIt-Session-Id: ${EOI_SESSION_ID}", and --header "X-CSRF-Token: ${EOI_CSRF_TOKEN}". Send additional operation headers such as If-Match when required.

Check authority before writing

The server checks capabilities along with role, organization, camera grants, ownership, and licensing. Some operations require a provider administrator even when a token has the corresponding capability. User sessions may require recent password/MFA confirmation through /auth/reauthenticate. Complete required password changes or MFA enrollment before other API work.

Workspace switching rotates session and CSRF credentials. After switching, replace the cookie jar contents, CSRF token, and session ID using the new response. The workspace guide explains the sequence.

End the session

curl --fail-with-body --silent --show-error \
  --request POST \
  --cookie "$EOI_COOKIE_JAR" \
  --header "X-EyesOnIt-Session-Id: ${EOI_SESSION_ID}" \
  --header "X-CSRF-Token: ${EOI_CSRF_TOKEN}" \
  "${EOI_API_BASE_URL}/auth/logout"
rm -rf -- "$EOI_SESSION_DIR"
unset EOI_SESSION_DIR EOI_COOKIE_JAR EOI_SESSION_ID EOI_CSRF_TOKEN EOI_SERVICE_TOKEN

Treat the cookie jar and session response as credentials. Delete their temporary directory after use.