Issue a service token

An EyesOnIt server administrator issues a service token for the Genetec plugin or another approved integration. Run the commands below in a Bash terminal on the backend host. In Windows WSL, use the Ubuntu terminal running that backend.

The token authenticates the integration to EyesOnIt. It is separate from your license key, license-server authorization token, web account password, and Genetec sign-in. Reinstalling the plugin does not invalidate an existing token. Reuse the saved credential when it remains authorized; issue a replacement if it was lost or revoked.

1. Select the backend storage

Choose one of the following setups, then keep the same terminal open for issuance and revocation. These instructions cover a single native backend. For a Docker deployment, use the administration tooling inside the API container with that deployment’s mounted store and key; the host-native paths below do not select a container’s database.

Installed native service

The guided native installer uses these paths by default:

EOI_ADMIN=/opt/eyesonit/current/venv/bin/eoi-admin
EOI_STORE=/var/lib/eyesonit/control/state.sqlite3
EOI_MASTER_KEY=/etc/eyesonit/secrets/security-master-key

If the installation uses a custom data root, use its existing control database. Check EOI_DATA_ROOT in /etc/eyesonit/backend.env and /etc/eyesonit/runtime.env, and the LoadCredential=security-master-key: path in systemctl cat eoi-api.service. Read only the relevant paths; do not share complete environment or credential files.

Local source development backend

Use the source checkout that runs eoi-backend-dev.service. Change /path/to/eoi-backend to that checkout’s directory:

cd /path/to/eoi-backend
EOI_ADMIN="$PWD/.venv/bin/eoi-admin"
EOI_STORE="${XDG_DATA_HOME:-$HOME/.local/share}/eyesonit/native-dev/data/control/state.sqlite3"
EOI_MASTER_KEY="${XDG_CONFIG_HOME:-$HOME/.config}/eyesonit/native-dev/credentials/security-master-key"

Run this as the development user who owns the backend, before invoking sudo below. The standard source setup keeps configuration in ~/.config/eyesonit/native-dev and data in ~/.local/share/eyesonit/native-dev. For custom paths, check systemctl --user cat eoi-backend-dev.service and its referenced backend.env. The development database is separate from /var/lib/eyesonit.

Check the selected files

Confirm that the CLI, populated database, and existing key are present before issuing anything:

sudo test -x "$EOI_ADMIN" &&
  sudo test -s "$EOI_STORE" &&
  sudo test -s "$EOI_MASTER_KEY" &&
  sudo "$EOI_ADMIN" issue-service-token --help

Continue only if this succeeds and the paths belong to the backend you intend to connect. Do not create a new database or generate a new master key to resolve a missing-file error.

2. Issue the Genetec plugin token

This example supports camera configuration and control, incidents, archive and live search, identities, authenticated media, realtime updates, shared gateways, and Genetec Web SDK settings. Remove capabilities for features the integration will not use. system:manage permits shared server configuration; reserve this token for trusted integration administrators.

sudo "$EOI_ADMIN" \
  --store "$EOI_STORE" \
  --master-key "$EOI_MASTER_KEY" \
  issue-service-token \
  --name "Genetec plugin" \
  --scope monitor:read \
  --scope streams:control \
  --scope streams:configure \
  --scope cameraOrganization:manage \
  --scope incidents:read \
  --scope incidents:acknowledge \
  --scope incidents:disposition \
  --scope searches:read \
  --scope searches:execute \
  --scope identities:read \
  --scope identities:manage \
  --scope media:read \
  --scope realtime:read \
  --scope gateways:configure \
  --scope alerts:deliver \
  --scope system:read \
  --scope system:manage

The command prints JSON with tokenId, name, scopes, and credential. The credential is disclosed only at issuance. Save it in your approved secret store and retain tokenId for revocation. Do not record the terminal, paste the output into support messages, or commit it. A lost credential must be replaced; token metadata cannot reveal it again. Issuance does not require a backend restart.

Service tokens are provider integration credentials with explicit capabilities. They do not impersonate a Genetec operator or supply customer workspace identity. On shared hosting, customer and provider-administrator operations can require a browser account even when a service token has the named capability. The legacy EOI_API_TOKEN compatibility credential is rejected after named-customer hosting begins.

3. Configure and verify the plugin

1. Open Options → EyesOnIt → EyesOnIt Server in Config Tool or Security Desk.
2. Enter the backend origin in Server URL, using a hostname covered by its trusted HTTPS certificate. The standard local source backend uses http://127.0.0.1:8000 on the same Windows/WSL workstation; this loopback development address is separate from the production HTTPS setup.
3. Paste only the credential value into API bearer token, without JSON quotes or the Bearer prefix.
4. Choose Test Connection, then Apply/OK. The saved token is protected with Windows DPAPI for the current Windows user.
5. Open Investigation or Monitoring and verify its realtime status becomes Connected. API readiness, realtime connection, camera video, and event delivery are separate checks.

Configure each Windows user and client installation that needs the connection. Reinstallation under the same user may preserve it; a different Windows user cannot decrypt another user’s saved token.

To check authentication directly, enter the backend origin and token at the prompts. The header goes to curl through standard input so the secret is absent from its command arguments:

read -rp "EyesOnIt origin (for example https://eyesonit.example.com): " EOI_SERVER
read -rsp "EyesOnIt service token: " EOI_SERVICE_TOKEN
printf '\n'
printf 'Authorization: Bearer %s\n' "$EOI_SERVICE_TOKEN" |
  curl --fail-with-body --silent --show-error \
    --header @- "${EOI_SERVER%/}/api/v1/auth/principal"
unset EOI_SERVICE_TOKEN

Check that kind is serviceToken and capabilities contains the issued scopes. For a private CA, configure curl to trust the public CA certificate, for example with --cacert /path/to/public-ca.crt; keep certificate verification enabled. A 401 usually requires the correct backend/token or a replacement token. A 403 requires reviewing capabilities and the operation’s account or workspace requirements.

Replace or revoke a token

For a planned replacement, issue a new token, update and test every authorized client using the old one, then revoke the old token. If a token was exposed, revoke it promptly and update affected clients.

In the terminal where you selected the correct backend paths, enter the old tokenId from issuance or the authorized GET /api/v1/service-tokens metadata response:

read -rp "Token ID to revoke: " EOI_TOKEN_ID
sudo "$EOI_ADMIN" \
  --store "$EOI_STORE" \
  --master-key "$EOI_MASTER_KEY" \
  revoke-service-token --token-id "$EOI_TOKEN_ID"
unset EOI_TOKEN_ID

The result reports revoked: true. Clients using that credential must be configured with an authorized replacement. The REST administration endpoints also support listing and revocation; token creation uses the root-only server CLI.