Sensors and keys

Sensors authenticate browser extensions, desktop agents, gateway integrations, and MCP reports. Each new key belongs to one organization, is authorized for one environment, and expires. It is a machine credential—not a web login or a provider API key.

Provision a key

1. Open Operations → Sensors & keys as an organization administrator.
2. Select Create Key.
3. Select exactly one allowed environment: Browser extension, Desktop agent, MCP agent, or AI gateway.
4. Choose a 30-, 90-, or 365-day lifetime. Ninety days is the recommended default.
5. Use a label that identifies the deployment group, device, or integration.
6. Copy the raw key when it appears. Orthalon stores a hash and cannot display the raw value again.
7. Place it in managed browser configuration, an endpoint secret/profile, or a server-side secret store.

For local repository testing, use the scope-specific root variable shown by the success panel:

The ingest service has no sensor key of its own. It validates the four scoped credential types. Never place a Browser, Desktop, MCP, or Gateway key in another environment, even when the same user and organization own both.

Do not commit the key, send it in email/chat, put it in browser application code, or reuse one credential across environments. Prefer one key per device or small deployment group so a single revocation has limited impact.

Orthalon does not support a universal, all-environments credential. Database migrations that introduce scoped credentials revoke older unscoped keys. After applying the migration, provision a fresh key for each environment you operate.

Credentials issued under an earlier product name must also be revoked and recreated. Do not edit an old key's visible prefix: the complete raw value is authenticated against its stored hash. A renamed prefix on an old secret is not a valid Orthalon credential.

What a leaked key permits

A leaked key does not grant access to the Orthalon web account and cannot edit organization policies. It can impersonate the environment named by its scope:

• browser or desktop keys can download that organization's endpoint policy and submit false metadata-only events for their own surface;
• an MCP key can submit false sanitized MCP inventory on Enterprise;
• a gateway key can attribute gateway traffic to the organization, although a separate model-provider credential is still required to call the provider.

An attacker may pollute discovery, violations, approvals, and compliance evidence or consume service capacity. Orthalon therefore enforces scope, expiration, payload limits, and per-key request limits at the server. These controls reduce impact but do not make a leaked credential safe.

Respond to a suspected leak

1. Revoke the key immediately under Operations → Sensors & keys.
2. Provision a replacement with the same single-environment scope.
3. Update only the affected browser group, endpoint, or server integration.
4. Review events, approvals, MCP inventory, last check-in, and audit logs from the suspected exposure window.
5. Remove fabricated records from compliance evidence and record the incident.

Revocation stops new authenticated requests immediately. A browser or desktop agent may continue applying its last cached policy locally while offline, but it cannot refresh policy or send telemetry with the revoked credential.

Verify health

The sensor list shows device or integration identity, version, last check-in, and status. After enrollment:

• confirm the sensor belongs to the intended organization;
• confirm its policy version updates after a policy change;
• investigate devices that have not checked in for more than seven days;
• compare enrolled sensors with the employee or application scope you intended.

Rotate a key

Sensor keys are rotated by provisioning a replacement, distributing it, and revoking the old key.

1. Provision the replacement.
2. Update a small pilot group or non-production integration.
3. Confirm successful policy and event requests.
4. Complete distribution.
5. Revoke the old key and verify it receives an unauthorized response.

Diagnose authentication errors

• 401: missing, malformed, expired, or revoked sensor key.
• 403: the key is valid, but its organization plan cannot use the requested feature or its scope does not allow that endpoint.
• 429: the credential exceeded its per-key request limit; inspect the deployment for a retry loop or misuse and honor retry-after.
• No check-in: incorrect ingest URL, network/DNS issue, stopped endpoint service, or browser policy not applied.

Create and verify the web account and organization before generating the key. A random value placed in ORTHALON_SENSOR_KEY is not a valid Orthalon credential.