Skip to main content

Identity & Keys

Each SLAW instance has two identity primitives: a stable machine ID that never changes, and a per-instance API key issued at enrollment. Together they let the tower authenticate ingest traffic and revoke access for a specific instance without affecting others.

Prerequisites: Familiarity with the Reporting Protocol. Identity values are sent in every enroll request.

Machine ID​

The machine ID (machineId) is a salted hash derived from stable hardware or OS identifiers on the host machine. It is generated once on first SLAW startup and stored at:

~/.slaw/machine.json
PropertyValue
Location~/.slaw/machine.json
Length8–128 characters
FormatOpaque string (salted hash)
StabilityPersistent across SLAW restarts and upgrades
UniquenessPer physical or virtual machine

The machine ID is included in every enroll request as instance.machineId. The tower displays the first 8 characters in Fleet View to help Operators identify machines at a glance without exposing the full value.

Needs verification

The exact hashing algorithm and salt source used to derive machineId are not documented in the protocol package. QA: verify against slaw/packages/shared/src/ or slaw/packages/botfather-reporter/src/ at fact-check time.

Auto-approve rules​

Operators can configure auto-approve rules based on machineId patterns (for example *-ENG-* to auto-approve any machine whose ID contains -ENG-). See Approvals & Admin for how to configure these rules.

Instance ID​

The instance ID (instanceId) is a stable, human-readable identifier for this SLAW installation — separate from the machine ID.

PropertyValue
FormatAlphanumeric, hyphens, and underscores — [a-zA-Z0-9_-]
Max length64 characters
ScopeIdentifies the SLAW process/installation, not the machine

Multiple SLAW instances can share a machine (for example in CI or multi-tenancy setups). Each gets its own instanceId and its own API key.

API keys​

The tower issues one API key per instance at the moment of enrollment approval.

Issuance​

When an enrollment transitions to active — either immediately via an auto-approve rule or after an Operator approves — the tower returns the key in the enrollment response:

{
  "enrollmentId": "550e8400-...",
  "state": "active",
  "apiKey": "slawbf_live_...",
  "pollIntervalSec": 10
}

The key is returned once only. The instance must store it locally. It is never retrievable from the tower after this point.

Storage​

The instance stores the API key locally (location is SLAW-internal). It is sent as a Bearer token on all authenticated ingest calls:

Authorization: Bearer slawbf_live_...

Hashing and lookup​

Needs verification

The following reflects 02 §4.9 requirements. QA: verify the exact Argon2 variant, parameters, and column names against slaw-botfather/server/src/ at fact-check time.

The tower never stores plaintext API keys. On receipt, it:

  1. Computes a SHA-256 fingerprint of the raw key for fast lookup.
  2. Stores an Argon2 hash of the key for verification.

On each authenticated request:

  1. The tower extracts the key from the Authorization header.
  2. It looks up the record by SHA-256 fingerprint (fast index scan).
  3. It verifies the key against the stored Argon2 hash.

This two-step approach keeps lookup fast (fingerprint index) while ensuring the stored value is computationally expensive to brute-force (Argon2).

Revocation​

An Operator can revoke any instance's API key from the tower UI (Approvals & Admin screen). On revocation:

  • The instance's enrollment state becomes revoked.
  • All subsequent authenticated requests from that instance return HTTP 403 with code enrollment_revoked.
  • The instance enters the revoked gate state and stops reporting.

To re-admit a revoked instance, the Operator re-approves it (or re-enrollment is triggered from the instance side). A new API key is issued.

Enrollment states​

The tower tracks each instance's enrollment state. The instance reads its current state from enroll and poll responses.

StateMeaning
pendingEnrollment received; awaiting Operator approval.
activeApproved and reporting. API key is valid.
rejectedAn Operator rejected the enrollment. Instance cannot report.
revokedPreviously active, now revoked. API key is invalid.

Next steps​