Authentication

Koban Fleet authenticates steady-state sensor traffic with tenant sensor tokens. This is the primary, managed authentication method, and it is what hosted Fleet uses by default. Self-hosted enterprise deployments can instead enable mTLS, where a device client certificate authenticates sensor traffic and token authentication is turned off.

Auth model

Operator and product API access uses a separate admin token, not sensor credentials. See Product API auth.

Tenant sensor tokens

A tenant sensor token is the credential the Koban agent presents on every protected sensor request. Its properties:

• Tenant-scoped. Each token maps to exactly one tenant. Config, check-in, and sync requests are rejected if the request tenant_id does not match the token's tenant.
• One active per tenant. Fleet allows a single active sensor token per tenant. Creating a new one while an active token exists fails, so rotate instead.
• Hashed at rest. Fleet stores only a hash of the secret. The plaintext is shown once, at creation or rotation, and can never be retrieved again.
• Sent as a header. The agent attaches it to protected sensor requests:

X-Koban-Sensor-Token: <token>

Manage tokens in Fleet

The Sensor Tokens page in Fleet manages the lifecycle:

• Create issues the tenant's sensor token and reveals the plaintext secret once. Copy it immediately. It is hashed on the server and cannot be shown again.
• Rotate revokes the active token and issues a replacement in one step. The old secret stops working the moment you rotate, so every sensor still using it will fail to sync, check in, or pull config until you deploy the new secret. This cannot be undone.
• List shows token metadata (ID, status, created, last used). Plaintext secrets are never listed.

Distribute the secret to your Macs through your MDM, the same way you would any other managed secret. Rotate on a schedule and whenever a secret may have been exposed.

Product token API

Operators and automation can manage sensor tokens over the product API. These routes require an admin token (X-Koban-Admin-Token) and the admin role:

Enrollment

Before a Mac can sync, it registers with Fleet to obtain its device identity. The agent:

1. Generates a device key locally.
2. Sends a short-lived enrollment token and its public key to /api/sensor/v1/enroll.
3. Receives device identity material (its tenantID and deviceID), plus a client certificate for deployments that use mTLS.
4. Stores enrollment state locally and stores identity material in the macOS Keychain.

Treat enrollment tokens like bootstrap credentials: issue them narrowly, template them through your MDM, rotate them, and expire them quickly. Enrollment is the only sensor route reachable before a device has identity material, because a new device cannot present credentials it has not been issued yet.

Steady-state sync

After registration, the agent talks to Fleet over outbound HTTPS. On managed Fleet it presents the tenant sensor token for:

• Fetching the canonical JSON configuration bundle
• Sending check-ins
• Uploading observations, inventory updates, and findings

Fleet verifies that the token's tenant matches the tenantID and deviceID in the request body. A request cannot sync as a tenant its token does not belong to.

Sensor routes

The open sensor protocol is JSON-first. These are the v1 HTTP routes:

Enrollment is the only sensor route that does not require an existing credential. Config, check-in, and sync requests include tenant and device IDs in the body, and Fleet checks those IDs against the authenticated identity.

mTLS for self-hosted enterprise

Self-hosted Fleet deployments can require mutual TLS for protected sensor routes. When the backend is configured with an mTLS CA (KOBAN_MTLS_CA_FILE):

• The device client certificate issued during enrollment authenticates config, check-in, and sync.
• The certificate's identity (tenant and device) must match the IDs in the request body. A certificate for one device cannot sync as another device.
• Sensor token authentication is disabled. Protected routes require a verified client certificate.

mTLS is aimed at enterprise customers who run their own Fleet and want certificate-based device identity instead of a shared tenant secret. The managed Fleet service uses tenant sensor tokens.

Local development

For local or self-hosted backends without mTLS, a shared development sensor token (KOBAN_SENSOR_TOKEN, seeded as dev-sensor-token in Docker Compose) lets the agent authenticate without provisioning a real token. Leave it empty in production and use a tenant sensor token created in Fleet.

Product API auth

Fleet operator APIs use admin tokens, not sensor credentials. Those APIs create sensor tokens, publish config, list devices, and review findings. Mutating operator actions require the admin role.

Sensor credentials and operator credentials are separate on purpose: a Mac can upload its own observations, but it cannot publish policy or manage tokens.

YAML for humans, JSON for systems

Humans can author Fleet configuration as YAML. Fleet validates that YAML against Koban's closed rule vocabulary, canonicalizes it to JSON, and serves the JSON bundle to enrolled agents.

Agents do not need to parse remote YAML. Local agent configuration remains YAML because it is edited by people on a Mac. Remote Fleet configuration is JSON because it is the wire protocol between systems.

What is not authenticated this way

Koban does not grant Fleet remote command execution on endpoints. Authenticated sensor routes are for configuration delivery, check-in, and upload. Rules still run locally on the agent, and findings are reports rather than enforcement actions.

Config signatures are reserved for a future offline-verification mode. In v1, transport security and the authenticated sensor identity (tenant sensor token, or device certificate under mTLS) are the production auth boundary.