APIX IoT Device Profile: Discovery and Presence for Connected Device Services

1.2.1. Hub-Mediated Device Services

Many IoT devices communicate exclusively over short-range mesh protocols (Matter over Thread, Zigbee, Z-Wave) and have no direct path to the public internet. These devices are physically incapable of sending presence signals to APIX themselves. A hub gateway -- an internet-capable device that bridges the local mesh to the IP network -- must act as their APIX presence relay.¶

APIX supports this through two complementary registrations: a hub device class (type hub) for the gateway hardware, and a hub-mediated device class (presence_mode hub) for the devices the hub serves.¶

Hub entity¶

A hub is registered in APIX as a device class with spec.type: "hub". Hub physical units receive their own instance tokens at manufacture, identical in structure to device instance tokens. Hubs signal their own presence directly to the APIX presence endpoint (presence_mode push). A hub instance that is offline cannot relay presence for any of its connected devices.¶

{
  "apm_version": "1.0",
  "service_id": "UUID v4 -- stable hub class identifier",
  "name": "Haustec Connect Bridge v2",
  "description": "Matter/Thread hub for BSH home appliances",
  "lifecycle_stage": "stable",
  "owner": {
    "organisation_name": "BSH Home Appliances GmbH",
    "jurisdiction": "DE",
    "registration_number": "HRB 123456",
    "contacts": {
      "operations": "apix-ops@bsh-group.com",
      "escalation": "apix-escalation@bsh-group.com"
    }
  },
  "spec": {
    "type": "hub",
    "hub_protocols": ["matter"],
    "supported_device_classes": ["dc-haustec-pro8-dishwasher"],
    "presence_mode": "push",
    "apix_presence_protocols": ["v1"],
    "heartbeat_interval_seconds": 60,
    "max_offline_seconds": 180
  }
}

supported_device_classes is the exhaustive list of device class IDs for which this hub type may relay presence signals. APIX MUST reject hub-relay signals for device classes not in this list.¶

Hub-mediated device class¶

A device class whose physical instances cannot signal directly sets presence_mode: "hub" in its APM. It also declares hub_protocols to identify how the hub-to-device local channel carries the instance token during the pairing process.¶

{
  "spec": {
    "type": "device-class",
    "presence_mode": "hub",
    "hub_protocols": ["matter"],
    "permitted_hub_classes": ["hc-haustec-connect-bridge-v2"],
    "api_base_url": "https://api.haustec.example/hub-gateway/api",
    "supported_api_versions": ["1.0", "1.1"],
    "apix_presence_protocols": ["v1"],
    "heartbeat_interval_seconds": 300,
    "max_offline_seconds": 600
  }
}

hub_protocols informs APIX and consuming agents which local protocol carries the device's instance token to the hub at pairing time. The mechanism for token transfer is hub-protocol specific and outside the scope of this specification.¶

permitted_hub_classes is an optional field. When present, it is a manufacturer capability declaration that restricts which hub classes may relay presence signals for instances of this device class. APIX MUST reject relay signals from hub instances whose class ID is not in the list. When absent, any hub whose supported_device_classes includes this device class may relay.¶

This field is a capability and interoperability declaration, not a per-instance pairing or authentication mechanism. It encodes the manufacturer's knowledge of which hub types their device is designed to work with correctly. Instance-level device-to-hub pairing is governed by the local network provisioning process (for example, Matter commissioning) and the manufacturer's device management infrastructure; it is outside the scope of this specification.¶

Hub-relay presence signal¶

A hub signals presence for a connected device using a dedicated hub-relay endpoint. Each signal carries two credentials: the hub's own instance token in the Authorization header (authenticating the hub), and the paired device's instance token in the request body (authenticating the specific device). APIX validates both independently.¶

POST https://apix.example.org/presence/v1/hub-relay/register
Authorization: Bearer hub-instance-token
Content-Type: application/json

{
  "hub_instance_id": "di-hub-a4c27f...",
  "signal_type": "register",
  "device": {
    "instance_token": "device-instance-token",
    "device_class_id": "dc-haustec-pro8-dishwasher",
    "api_version": "1.0"
  },
  "hub_gateway_endpoint":
    "https://api.haustec.example/hub-gw/api/1.0/di-f47ac1..."
}

Note that hub-mediated device presence signals carry no network.ipv6 field: the device has only a local mesh address, which is not internet-routable and MUST NOT be included. The agent reaches the device exclusively via the hub_gateway_endpoint at the manufacturer's cloud, which routes requests to the device through the hub.¶

APIX MUST reject a hub-relay signal where: (a) the hub instance token is invalid or revoked, (b) the device instance token is invalid or revoked, (c) the device class is not in the hub class's supported_device_classes, (d) the hub instance is not itself currently online, or (e) the device class declares permitted_hub_classes and the relaying hub's class ID is not in that list.¶

Layer 2 instance record for hub-mediated devices¶

{
  "instance_id": "di-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "device_class_id": "dc-haustec-pro8-dishwasher",
  "api_version": "1.0",
  "online": true,
  "presence_mode": "hub",
  "hub_instance_id": "di-hub-a4c27f...",
  "last_seen_at": "2026-04-24T09:00:00Z",
  "api_endpoint": {
    "hub_gateway":
      "https://api.haustec.example/hub-gw/api/1.0/di-f47ac1..."
  },
  "owner_id": "usr-7e8a9b2c...",
  "claimed_at": "2026-01-10T10:00:00Z",
  "_links": {
    "self": {
      "href": "https://apix.example.org/devices/di-f47ac1..."
    },
    "hub": {
      "href": "https://apix.example.org/devices/di-hub-a4c27f..."
    },
    "device_class": {
      "href": "https://apix.example.org/device-classes/dc-haustec-p8"
    }
  }
}

Cascading offline¶

When a hub instance is marked offline -- whether by heartbeat timeout or explicit departure signal -- APIX MUST mark all device instances currently attributed to that hub as offline and MUST clear their api_endpoint.hub_gateway fields. APIX MUST NOT return online: true for any device instance attributed to an offline hub.¶

Hub migration¶

A device may move from one hub to another. When a hub-relay register signal is received for a device whose instance record is currently attributed to a different hub, APIX MUST update the device instance record: hub_instance_id is set to the new hub's instance_id and api_endpoint.hub_gateway is replaced with the value from the new signal. The device instance_id MUST be preserved. APIX MUST return HTTP 409 device_not_attributed_to_hub on any subsequent hub-relay signal from the previous hub for that device.¶

Trust boundary¶

Hub relay introduces an intermediary trust boundary absent from the push model. The device's instance token validates that the specific device was genuinely provisioned for this class and class owner, but the hub's reported api_version and hub_gateway_endpoint are attested by the hub and cannot be independently verified by APIX. A compromised hub can misrepresent the state of devices it genuinely controls but cannot forge presence signals for devices whose instance tokens it does not hold.¶

Device classes using presence_mode: "hub" are bounded at service trust level S-1. S-2 (Spec Verified) requires a direct device signal path and is not achievable via hub relay in this specification version.¶

  Physical Device  (mesh -- Thread/Zigbee/Z-Wave, not internet-capable)
  +------------------------------------------+
  | instance_token  (in secure enclave)       |
  | api_version     firmware API version      |
  | local_mesh_addr NOT internet-routable     |
  +------------------------------------------+
             |
             | hub protocol (Matter/Zigbee/Z-Wave)
             | pairing: hub reads instance_token
             v
  Hub Instance  (internet-capable border router)
  +------------------------------------------+
  | hub_instance_id    own APIX identity      |
  | hub_instance_token own APIX credential    |
  | paired devices:    [{instance_token,...}] |
  +------------------------------------------+
             |
             | POST /presence/v1/hub-relay/register
             | Auth: hub_instance_token (hub identity)
             | Body: device instance_token (device identity)
             v
  +---------------------+------------------------+
  | Layer 1  (PUBLIC)   | Layer 2  (PRIVATE)     |
  | hub class metadata  | hub instance: online   |
  | device class meta   | device instance:       |
  | no instance data    |   hub_instance_id      |
  |                     |   api_endpoint.        |
  |                     |     hub_gateway        |
  +---------------------+------------------------+
          ^                         ^
          |                         |
  anonymous agent           authenticated agent
  class discovery           GET /devices?online=true

1.2.2. Device Class Lifecycle

Device class lifecycle is defined by this profile. Valid lifecycle_stage values for device classes are stable, deprecated, and end_of_life. These are the complete set for this service type.¶

A device class progresses through three lifecycle stages that the manufacturer sets via registration updates. Transitions are unidirectional: stable → deprecated → end_of_life.¶

stable — Full operation. All normative rules apply without modification.¶

deprecated — The manufacturer is winding down the class. APIX MUST continue accepting presence signals from existing device instances. Deprecated classes MUST be excluded from Layer 1 capability searches by default; they remain directly retrievable by service_id. Device instances of deprecated classes MUST be excluded from Layer 2 query results by default; a consuming agent MAY include them by adding include_deprecated=true to the query. Instance records MUST carry "class_lifecycle_stage": "deprecated".¶

end_of_life — APIX MUST reject all presence signals for the class with HTTP 410 Gone. All existing instances are marked online: false and reachable: false. Class and instance records are retained for historical query by the device owner but MUST NOT appear in any capability or instance search.¶

1.2.3. Instance Reachability

A device instance MUST be marked "reachable": false when its current api_version is absent from the device class's current supported_api_versions list. This condition arises when a manufacturer removes a version from the supported list -- for example, as part of a class deprecation cycle -- while one or more physical devices remain on that version. Such a device is still online (liveness signals continue to be accepted) but its API version is no longer endorsed, so no valid endpoint can be constructed by a consuming agent.¶

APIX MUST exclude instances with reachable: false from query results regardless of the online filter value. A query for online=true devices MUST NOT include an instance that is reachable: false.¶

When reachable: false, instance records MUST omit api_endpoint fields. The api_version field is retained to allow the owner to identify the version mismatch.¶

Instance records MUST include "reachable": false and "class_lifecycle_stage" (with its non-stable value) whenever those conditions apply. Neither field is present in the response when the instance is reachable and its class is stable.¶

1.6.1. Delegation Model

A device owner MAY delegate access to specific device instances to an autonomous agent. Delegation is explicit, scoped, time-bounded, and revocable. It does not expose the instance to any other agent and does not modify the instance record visible to other principals.¶

Delegation is distinct from consumer token issuance. A consumer token identifies a principal (human or organisation). A delegation grant authorises a specific agent, identified by its own consumer token, to act on behalf of the owner for a defined set of operations on a defined set of instances.¶

1.6.2. Delegation Scopes

The following delegation scope values MUST be supported:¶

Scopes are additive. A delegation grant MUST specify at least one scope. devices.command MUST NOT be granted without also granting devices.read, as command routing requires knowledge of the current api_endpoint.¶

1.6.3. Delegation Grant API

The owner creates a delegation grant via the APIX delegation endpoint:¶

POST /devices/{instance_id}/delegations
Authorization: Bearer owner-consumer-token
Content-Type: application/json

{
  "agent_token_id": "token_id of the agent's consumer token",
  "scopes": ["devices.read", "devices.command"],
  "expires_at": "ISO 8601 timestamp -- REQUIRED",
  "note": "human-readable description -- OPTIONAL"
}

agent_token_id is the non-secret token identifier of the agent's registered consumer token. The owner does not need to hold or transmit the agent's token secret; the token_id is sufficient for APIX to resolve the delegation at query time.¶

expires_at is REQUIRED. Perpetual delegation grants are not permitted. Maximum delegation duration MUST be enforced by the index operator; the RECOMMENDED maximum is 365 days. Owners SHOULD grant the minimum duration sufficient for the agent's task.¶

APIX MUST return the delegation grant identifier (delegation_id) in the response. The owner uses delegation_id to list, inspect, and revoke grants.¶

1.6.4. Delegated Agent Query

An agent that holds a valid delegation grant queries device instances using its own consumer token:¶

GET /devices/{instance_id}
Authorization: Bearer agent-consumer-token

APIX MUST resolve the delegation at query time: if a valid, non-expired delegation grant exists for the requesting token_id covering the requested instance_id with the devices.read scope, APIX MUST return the full Level 2 instance record as if the agent were the owner.¶

If no valid delegation exists, APIX MUST return an empty result (consistent with the enumeration prevention requirement in Section 6.2).¶

1.6.5. Delegation Revocation

An owner revokes a delegation by calling:¶

DELETE /devices/{instance_id}/delegations/{delegation_id}
Authorization: Bearer owner-consumer-token

Revocation is immediate. Any in-flight agent request that has not yet received a response at the time of revocation MUST return an empty result. APIX MUST NOT return instance data to a revoked delegation.¶

Delegation grants are also revoked automatically when: - The delegation expires_at timestamp is reached - The owner releases their ownership claim on the instance - The agent's consumer token is revoked by the agent itself or by APIX - The instance is placed in quarantine state (fleet circuit breaker)¶

1.6.6. Delegation and Privacy

Delegation grants are personal data: they link a device owner identity to an agent identity. They MUST be subject to the same data minimisation and retention rules as other personal data in device instance records. On receipt of a device owner erasure request, all delegation grants for that owner's instances MUST be revoked and deleted.¶

1.8.1. Instance Token Security

Device instance tokens are long-lived secrets stored on constrained hardware. Implementors MUST store tokens in hardware-backed secure storage (secure enclave, TPM, or equivalent) where the device platform supports it. Tokens MUST NOT be transmitted in log output, diagnostic APIs, or any channel other than the APIX presence endpoint Authorization header.¶

The token_id is a non-secret correlation handle. It MAY be logged and MAY appear in diagnostic interfaces without security risk.¶

1.8.2. Layer 2 Enumeration Prevention

APIX MUST return an empty result set (not HTTP 404 or HTTP 403) for authenticated queries that would match instances belonging to other principals. An attacker with a valid consumer token MUST NOT be able to determine whether a given instance_id or device_class_id exists in the system by observing error responses.¶

1.8.3. Hub Compromise Scope

A compromised hub instance can misrepresent the state (online status, api_version, hub_gateway_endpoint) of devices it genuinely controls. It cannot forge presence signals for devices whose instance tokens it does not hold. The blast radius of a hub compromise is bounded to the set of devices paired to that hub. This is a smaller blast radius than cloud_relay compromise, where the manufacturer's cloud holds all fleet tokens.¶

1.8.4. Presence Signal Replay

APIX MUST enforce that presence signals are processed at-most-once within the heartbeat window. Duplicate signals within the same heartbeat_interval_seconds window MUST be idempotently accepted (no state change) rather than counted as separate registrations.¶

1.8.5. Physical Device Privacy

The two-layer model (Section 3) is a security requirement, not only a privacy preference. Index implementations MUST enforce it at the infrastructure layer. Returning instance-level data to unauthenticated queries is a critical vulnerability, not a configuration error.¶

1.8.6. APIX as a High-Value Attack Target

APIX occupies a structurally unique position: it is the single presence endpoint for potentially millions of physical devices and holds the mapping between device identifiers, network addresses, and owner identities at global scale. A full compromise of the APIX index is not a data breach in the conventional sense — it is a global occupancy intelligence leak combined with the ability to disable an arbitrary set of connected devices by mass-revoking their instance tokens. This threat profile requires architectural mitigations beyond standard application security.¶

APIX implementations MUST satisfy the following architectural requirements:¶

• The presence endpoint (which receives device signals) MUST be architecturally separated from the token store. A compromise of the presence endpoint infrastructure MUST NOT yield access to the token hash store or the Layer 2 owner-to-network-address mappings.¶

• APIX MUST NOT store plaintext device instance tokens at any point in the live system. Only the SHA-256 hash of each token is stored, as specified in Section 3. Hash storage and the presence endpoint MUST run in separate trust boundaries.¶

• Token issuance (the process by which new tokens are generated and delivered to manufacturers) MUST be performed in an air-gapped or hardware-security-module (HSM) isolated process. Token issuance infrastructure MUST NOT be reachable from the public internet.¶

• The presence endpoint MUST be geographically distributed across independent infrastructure regions. No single region outage or compromise MUST affect global device presence signalling.¶

• All administrative operations that affect token validity (revocation, suspension, fleet circuit breaker actions) MUST be recorded in a tamper-evident append-only audit log. This log MUST be replicated to at least two geographically separate locations. Log entries MUST be individually signed.¶

• APIX MUST publish an annual infrastructure security report disclosing the number of tokens issued, rotated, and revoked; the number of presence signals processed; and any confirmed security incidents.¶

1.8.7. Fleet Circuit Breaker

An emergency mechanism MUST be available to index operators to quarantine a compromised manufacturer fleet or a rogue device class at the index layer, without requiring physical access to the affected devices.¶

Two distinct compromise scenarios are addressed:¶

Scenario A — Manufacturer systems compromised. An adversary has gained access to the manufacturer's cloud infrastructure and is forging presence signals on behalf of real devices (false liveness, false network addresses, false api_version). The appropriate response is to suspend the manufacturer account and revoke all fleet tokens for the affected device classes, following the same atomic four-step procedure defined for sanctions suspension in [APIX-CORE]. Token revocation MUST trigger HTTP 401 token_revoked at the presence endpoint, and all affected instances MUST be marked offline immediately.¶

Scenario B — Devices themselves are weaponised. The physical devices are operating normally from the device credential perspective (valid tokens, authentic presence signals) but are under adversary control and are being used maliciously. In this scenario, revoking device tokens would brick legitimate consumer devices without stopping the threat. The appropriate response is presence signal suppression without token revocation:¶

APIX MUST support a quarantine state for individual device instances or entire device classes. In quarantine state:¶

• Presence signals from quarantined instances MUST continue to be accepted at the presence endpoint. The device is unaware of the quarantine; presence processing appears normal.¶

• api_endpoint fields MUST be withheld from all Layer 2 query responses for quarantined instances. The consuming agent receives an instance record showing the device as online but with no reachable endpoint. No agent can connect to the device through APIX.¶

• Quarantined instances MUST be excluded from Layer 1 capability searches, as if lifecycle_stage were end_of_life.¶

• The quarantine state MUST be reversible. When the quarantine is lifted, api_endpoint fields are restored and the instance returns to normal Layer 2 visibility.¶

• All presence signals received while an instance is quarantined MUST be logged with enhanced detail (source IP, signal content, timing) and retained for a minimum of twelve (12) months for law enforcement purposes.¶

The fleet circuit breaker MUST be operable at three scopes: instance (single device), device_class (all instances of a class), and manufacturer (all classes and instances under an organisation account). The scope MUST be explicitly declared in the activation record. Activation MUST require authorisation from at least two independent APIX operator roles (dual-control requirement).¶

1.8.8. Law Enforcement Cooperation Interface

APIX MUST provide a Law Enforcement Request (LER) interface: a restricted-access channel through which authorised public authorities may submit IP addresses of device instances identified as members of a malicious botnet, together with a suppression action request.¶

Accepted jurisdictions:¶

Two authority tiers are defined. Tier I covers supranational judicial instruments; Tier II covers national law enforcement requests. Both tiers require a judicial authorisation document. Administrative orders without judicial oversight MUST NOT be accepted at either tier.¶

Tier I — Supranational (automatically accepted):¶

Orders and provisional measures issued by the International Court of Justice (ICJ) are accepted automatically and are not subject to the Accepted Jurisdiction Whitelist. The ICJ is the principal judicial organ of the United Nations (ICJ Statute, June 1945). Its provisional measures under Article 41 of the ICJ Statute are legally binding on states and represent the highest-authority legal instrument available for cross-jurisdictional cases where no single national court has clear competence over a multi-state botnet operation. An LER citing a verified ICJ provisional measure or final judgment MUST be processed within 4 hours of receipt and is not subject to the 72-hour provisional reversal window; the suppression remains in force for the duration stated in the ICJ instrument.¶

Tier II — National law enforcement (whitelist-governed):¶

The LER interface MUST only accept requests from public authorities in jurisdictions that satisfy ALL of the following criteria:¶

• The jurisdiction has ratified the Budapest Convention on Cybercrime, OR is the domicile jurisdiction of the APIX governing body (currently Switzerland).¶

• The request is accompanied by a valid judicial authorisation document: a court order, magistrate warrant, or equivalent judicial instrument issued by a court of competent jurisdiction in the requesting state.¶

• The jurisdiction is included in the governing body's Accepted Jurisdiction Whitelist, maintained as a public document and updated by governing body board decision.¶

Jurisdiction Contact Registry:¶

The governing body MUST maintain a Jurisdiction Contact Registry (JCR) as part of the APIX operational infrastructure. The JCR is established during system ramp-up, before the LER interface is opened for submissions. A jurisdiction MUST NOT be added to the Accepted Jurisdiction Whitelist until all three mandatory contact roles have been confirmed for that jurisdiction.¶

Three contact roles MUST be registered per Tier II jurisdiction:¶

Operational contact — the national authority responsible for submitting LERs: typically the national cybercrime unit, CERT, or equivalent law enforcement body with cybercrime mandate (e.g., Bundeskriminalamt in Germany, ANSSI in France, FBI Cyber Division in the United States). This contact submits LER requests and provides the IP address lists.¶

Judicial contact — the authority responsible for obtaining and validating judicial authorisation: the Ministry of Justice, Attorney General, Prosecutor General, or equivalent government legal division with authority to commission court orders in the requesting jurisdiction. This contact is the issuing or co-signing party for the judicial authorisation document accompanying each LER. Including the judicial/legal division of government in the contact structure is REQUIRED — law enforcement submission without a validated judicial pathway is insufficient to activate the LER process.¶

Emergency contact — a named duty officer or on-call role reachable 24 hours a day, 7 days a week, for Tier I (ICJ) and emergency provisional national requests. MUST be distinct from the operational contact and MUST have authority to act on behalf of the jurisdiction without waiting for business-hours approval.¶

For the ICJ (Tier I), the governing body MUST establish contacts with the following bodies during system ramp-up:¶

• ICJ Registry (Greffe de la Cour): the administrative organ of the Court, responsible for receiving and communicating all instruments. Contact for standard ICJ instrument submission.¶

• President's Office of the ICJ: the authority responsible for ordering provisional measures under Article 41. Contact for time-critical ICJ provisional measure cases requiring 4-hour processing.¶

The governing body MUST formally notify each registered contact of the following at initial establishment and whenever the LER framework is materially updated:¶

1. The existence and purpose of the LER interface.¶

2. The legal basis under which APIX operates (Swiss Stiftung, Budapest Convention obligations, applicable data protection law).¶

3. The contact's specific role in the LER process and what actions are expected of them.¶

4. The APIX operational security contact and escalation path.¶

5. The jurisdiction's reference code in the JCR, to be cited in all LER submissions from that jurisdiction.¶

The governing body MUST review and re-confirm all JCR contacts at least annually. Contacts that cannot be confirmed MUST be flagged; the associated jurisdiction MUST be placed in suspended status on the Accepted Jurisdiction Whitelist until confirmed contacts are restored. A jurisdiction in suspended status MUST NOT submit new LERs; active suppressions from that jurisdiction remain in force.¶

Process tiers:¶

A national emergency provisional suppression that is not followed by verified judicial authorisation within 72 hours MUST be automatically reversed. The governing body MUST notify both the operational contact and the judicial contact of the reversal. ICJ-based suppressions are not subject to automatic reversal; they run for the duration specified in the ICJ instrument.¶

LER submission protocol:¶

The LER interface is a restricted-access HTTPS endpoint. It is not publicly documented or reachable from the open internet. Access is limited to network addresses registered for the jurisdiction's operational contact in the JCR.¶

Authentication: LER submissions MUST use mutual TLS (mTLS). Each registered operational contact is issued a client certificate by the APIX governing body at the time their jurisdiction is onboarded to the JCR. The certificate is scoped to the submitting jurisdiction's reference code. Certificate issuance and renewal is the governing body's operational responsibility.¶

Each JCR contact record MUST include a preferred_language field: a single BCP 47 language tag ([RFC5646]) indicating the language in which APIX conducts the voice callback verification with that contact. APIX MUST use this language for all spoken exchanges during the callback procedure, including reading the APIX TAN and requesting the personal verification code and uploader auth TAN. If the contacted person responds in a different language, APIX MUST treat this as an anomaly and log it, but MUST NOT reject the callback on language grounds alone. Example values: "de" for Bundeskriminalamt, "en" for FBI Cyber Division, "fr" for ANSSI.¶

In-jurisdiction dual authorisation: Each jurisdiction MUST register at least two named operational contacts in the JCR, each holding an independently issued client certificate. A single individual MUST NOT hold both certificates; APIX MUST enforce this by verifying that the countersigning contact's certificate subject is distinct from the submitting contact's certificate subject.¶

A valid LER submission MUST be countersigned by a second registered contact from the same jurisdiction before it enters the human review queue. The protocol uses a two-step commit:¶

1. The primary contact submits the LER via their authenticated mTLS connection. The submission is recorded with status pending_countersign and no review is initiated.¶

2. A second registered contact from the same jurisdiction MUST authenticate via their own mTLS certificate and issue a countersign request referencing the ler_id returned in the initial submission response. The countersign window is 60 minutes for standard and ICJ tier; 20 minutes for emergency_provisional tier.¶

3. If the countersign is not received within the window, the submission MUST be automatically rejected and logged with reason countersign_timeout. No review is initiated and no suppression is applied.¶

4. For emergency_provisional tier, the 4-hour processing commitment runs from the timestamp of the countersign, not the initial submission.¶

Submission endpoint:¶

The LER interface endpoint URL is not publicly published. It is communicated to each jurisdiction's registered operational contact as part of the JCR onboarding process. The interface requirements are:¶

POST <ler-endpoint-url>
Authorization: mTLS client certificate (jurisdiction contact)
Content-Type: application/json

The <ler-endpoint-url> is operator-specific and MUST NOT be discoverable from the public Index API. Implementations MUST ensure the LER endpoint is not reachable from network addresses outside those registered for the jurisdiction's operational contact in the JCR.¶

Request format:¶

{
  "jurisdiction_ref": "JCR reference code -- issued by APIX",
  "tier": "emergency_provisional | standard | icj",
  "judicial_ref": "court order or ICJ instrument reference number",
  "judicial_doc_url": "HTTPS URL -- APIX-verifiable document",
  "case_ref": "internal case reference of the submitting authority",
  "device_addresses": [
    {"type": "ipv4", "address": "203.0.113.42"},
    {"type": "ipv6", "address": "2001:db8::1"}
  ],
  "requested_scope": "instance | device_class | manufacturer",
  "requested_duration_hours": 168,
  "emergency_declaration": "tier: emergency_provisional only"
}

device_addresses MUST contain at least one entry. Bulk requests without specific device addresses (e.g., "all devices in jurisdiction X") MUST be refused per the Non-Surveillance Commitment in [APIX-CORE] Section 5.¶

requested_duration_hours is advisory. APIX MUST apply the suppression for the duration specified in the judicial instrument if it differs. For emergency_provisional, the suppression is automatically reversed after 72 hours unless judicial authorisation is verified (Section above).¶

Response format:¶

{
  "ler_id": "APIX-assigned unique LER identifier",
  "status": "accepted | refused | pending_countersign | ...",
  "estimated_processing_seconds": 14400,
  "refusal_reason": "null | invalid_jurisdiction | ... (see spec)",
  "apix_tan": "one-time code (pending_countersign only; null)",
  "uploader_auth_tan": "one-time code (countersign only; null)"
}

ler_id is the only external reference APIX issues for an LER case. It MUST be used in all subsequent communications about the case and is included in the annual transparency report aggregate statistics.¶

apix_tan and uploader_auth_tan are one-time codes generated per submission and returned only in the initial POST response when the submission is accepted for the countersign step. They are shown once and never again.¶

APIX MUST NOT provide any endpoint or mechanism to retrieve the TAN values after the initial POST response. The fields MUST be absent — not null, not redacted — from all subsequent API responses including LER status queries, countersign responses, and any other interface. No GET path to TAN values exists. This follows the same principle as one-time API key generation: if the recipient does not retain the values from the initial response, they are permanently unavailable.¶

Both codes expire upon completion of any verification exchange in which credentials are requested from the contacted person, regardless of whether the exchange results in confirmation or failure. An unanswered call attempt does not constitute a verification exchange and does not consume the codes. A new submission generates new codes; expired codes cannot be reissued for the same ler_id.¶

APIX MUST store both codes internally in a form that permits verification during the callback (hashed) but does not expose plaintext values through any interface after the initial POST response.¶

Countersign endpoint:¶

The second registered contact MUST submit the countersign via an authenticated request to the same LER interface:¶

POST <ler-endpoint-url>/countersign
Authorization: mTLS client certificate (second jurisdiction contact)
Content-Type: application/json

{
  "ler_id": "APIX-assigned LER identifier (initial submission)",
  "countersign_statement": "confirmation statement (see spec)"
}

Response:¶

{
  "ler_id": "...",
  "status": "countersigned | rejected",
  "rejection_reason": "null | window_expired | same_contact | ..."
}

On countersigned status, the submission transitions to the callback verification step (see below). On rejected, the submission is terminated and MUST be re-submitted from the beginning.¶

Submission callback verification:¶

After countersign is confirmed and before the submission enters the human review queue, APIX MUST perform a voice callback to the jurisdiction's registered operational contact. The callback uses three independent verification elements:¶

• APIX TAN — a one-time code returned in the initial submission response. APIX reads this to the contacted person at the start of the call, proving the caller is the legitimate APIX system.¶

• Personal verification code — a standing secret established per registered contact during JCR onboarding, known only to that individual and APIX. This code is never transmitted via any API or electronic channel.¶

• Uploader auth TAN — a one-time code returned in the initial submission response alongside the APIX TAN. The contacted person reads this back to APIX, binding the answering individual to the specific submission.¶

APIX MUST require both the personal verification code and the uploader auth TAN together in a single exchange. Neither alone constitutes confirmation.¶

The callback procedure is:¶

1. APIX retrieves the stored callback number from the JCR record for the submitting jurisdiction.¶

2. Immediately before initiating the callback (within 5 minutes of countersign confirmation), APIX MUST re-validate the stored number against the independent authoritative public source established at onboarding time.¶

3. If the stored number does not match the current public record, APIX MUST NOT call either number. The submission MUST be immediately suspended and an incident procedure initiated. No suppression is applied during suspension. The submission remains suspended until the incident is resolved and the callback number is re-established with confidence.¶

4. If the stored number matches the current public record, APIX initiates the call to the stored number and reads the APIX TAN. This allows the contacted person to verify they are speaking to the legitimate APIX system before providing any credential.¶

5. APIX then requests, in a single exchange: the contacted person's full name, personal verification code, and uploader auth TAN.¶

6. APIX verifies all three against its stored records. Any mismatch on any element MUST result in immediate termination of the call. No partial credit applies. The failure mode then determines the disposition (see below).¶

7. If the call is not answered on the first attempt, APIX MUST make one further attempt before permanently rejecting the submission. Two unanswered attempts exhaust the callback allowance. If the contact answers and a verification exchange begins, no further attempt is permitted regardless of outcome — the exchange result is final. If the contacted person explicitly denies any knowledge of the submission, the LER is permanently rejected with reason callback_verification_failed (see below).¶

Callback failure dispositions differ by cause and MUST be handled distinctly:¶

callback_verification_failed — operational failure, permanent rejection: Triggered when credential verification fails (wrong or absent uploader auth TAN or personal verification code), when the call is not answered after two attempts, or when the contact denies the submission. The LER is permanently rejected. This is not a security event: no Security Officer escalation is initiated. The jurisdiction MUST file a new LER; the rejected ler_id cannot be recovered. Logged as operational failure.¶

callback_number_mismatch — security event, submission suspended: Triggered when the stored callback number does not match the current public record at re-validation time (step 2 above). The submission is suspended pending incident resolution. Security Officer is notified. No suppression is applied. The submission remains suspended until the callback number is re-established with confidence and the incident is closed.¶

callback_interception_reported — confirmed security incident, submission suspended: Triggered when the contacted person reports having already received a call from a party claiming to be APIX before this call. The submission is immediately suspended. The Security Officer and a governing body board member MUST be notified. The incident is treated as a confirmed attempt to compromise the LER verification process and handled under the security incident response procedure in [APIX-CORE] Section 12.¶

The callback confirmation is a mandatory pre-condition for entering the human review queue. It does not substitute for the human review and dual-control activation procedure.¶

APIX MUST NOT acknowledge by any means that a suppression is active on a specific device or instance when responding to queries from parties other than the submitting jurisdiction. Device owner queries for affected instances MUST receive responses indistinguishable from an offline or unreachable instance.¶

Audit logging obligations:¶

Every event in the LER lifecycle MUST be written to the tamper-evident audit log defined in [APIX-CORE] Section 12. Log entries MUST be individually signed and immutable. The following events are individually logged:¶

The audit log MUST be the system of record for all LER activity. The annual transparency report derives its aggregate statistics from it; the log is the authoritative source and MUST be retained for a minimum of seven (7) years from the date of each entry.¶

Human authorisation and review:¶

APIX MUST NOT activate a suppression through a purely automated path. Every suppression activation requires human authorisation and post-hoc review by a named, accountable operator. The requirements differ by tier:¶

Standard and ICJ tiers:¶

1. Upon receipt of a valid LER submission (certificate valid, format valid, jurisdiction in accepted whitelist), the submission enters a human review queue. No suppression is active at this point.¶

2. A designated LER reviewer (a named APIX operator with the ler_review role) MUST read the submission and the referenced judicial document before authorising activation.¶

3. Activation MUST follow the dual-control requirement of the fleet circuit breaker ([APIX-CORE] Section 12): two independent operators with the ler_activate role MUST independently confirm before suppression is applied. Neither operator may be the same individual who reviewed the submission.¶

4. The activation record in the audit log MUST include the identities of both activating operators and the timestamp of each confirmation.¶

5. A post-activation review MUST be completed within 72 hours by a third operator (the LER oversight role) confirming that the activation was lawful, proportionate, and consistent with the judicial instrument scope. The review outcome MUST be recorded in the audit log.¶

Emergency provisional tier (4-hour window):¶

The 4-hour processing commitment creates time pressure. The following modified procedure applies:¶

1. Automated validation on receipt: certificate valid, jurisdiction in whitelist, emergency declaration field present, at least one device address specified. If validation passes, the submission immediately enters the emergency queue with an alert to the on-call LER reviewer.¶

2. The on-call LER reviewer MUST authorise activation within 4 hours. Activation requires only one authorising operator (single-control) in this tier due to the time constraint.¶

3. A second operator MUST complete a dual-control confirmation within 24 hours of activation. If the second confirmation is not received within 24 hours, the suppression MUST be automatically reversed.¶

4. The post-activation oversight review (step 5 above) MUST be completed within 24 hours of activation (not 72 hours) for emergency provisional cases.¶

5. Judicial authorisation MUST be verified within 72 hours (the automatic reversal window). If the judicial document review confirms the authorisation is invalid or the scope is exceeded, the suppression MUST be reversed immediately regardless of the dual-control confirmation in step 3.¶

Operator role structure:¶

The following named operator roles MUST be defined and staffed in the APIX operating model. No individual MUST hold more than two of these roles simultaneously (segregation of duties):¶

Role assignments MUST be published in the governing body's annual security report. Changes to role assignments MUST be logged in the audit log.¶

Any operator who receives an instruction — from any source, including governing body board members — to activate a suppression outside this procedure MUST refuse and MUST exercise the whistleblower protection right defined in [APIX-CORE] Section 12. This right is not waivable by role, contract, or board resolution.¶

Suppression effect:¶

LER-triggered suppression follows the fleet circuit breaker Scenario B model: presence signals continue to be accepted (the adversary controlling the botnet has no signal of identification), while api_endpoint fields are withheld from Layer 2 responses. The suppression scope is specified by the requesting authority as a list of device IPv4 and/or IPv6 addresses; APIX matches these against active presence signal source addresses.¶

APIX MUST NOT disclose to any party other than the requesting authority that a specific device instance is under LER-triggered suppression. Device owners querying their instance records MUST receive the same response as for any offline or unreachable instance; the suppression reason MUST NOT be disclosed.¶

Transparency:¶

APIX MUST publish aggregate LER statistics in its annual transparency report, disclosing: number of LER requests received by requesting jurisdiction, number accepted, number refused, number of provisional suppressions reversed, and number of device instances affected (by jurisdiction, not by individual identity). No individual case details, case references, or device identifiers MAY appear in the transparency report.¶

1.8.9. Bad-Bot Graduated Response

APIX MUST maintain a Bad-Bot Registry: a classified list of device instance identifiers and consumer token identifiers that have been confirmed as operating maliciously. Sources for registry entries include: LER submissions (Section 5.7), manufacturer abuse reports, and APIX operator investigation of anomalous signal patterns (e.g., rapid multi-instance registration from a single IP, heartbeat flooding, or token reuse patterns inconsistent with legitimate device operation).¶

Three response tiers are defined. The active tier for each registry entry MUST be explicitly recorded in the Bad-Bot Registry and MUST be changeable by operator action.¶

Tier 1 — observe (investigation in progress; entry not yet confirmed hostile or confirmation is recent):¶

• Presence endpoint: Accept signal normally. Instance record updated. HTTP 200 returned. No signal to the device that it is under observation.¶

• Consumer query endpoint: Full response returned normally.¶

• Logging: Enhanced. All presence signals and consumer queries from this identity MUST be logged with full detail (IP, payload, timing, response) and retained for a minimum of twelve (12) months.¶

Tier 2 — degrade (confirmed hostile; investigation active; covert restriction required to limit harm without alerting adversary):¶

• Presence endpoint: Accept signal normally (HTTP 200). Instance record updated to reflect online status. However, api_endpoint fields MUST be withheld from all Layer 2 query responses for the affected instance (fleet circuit breaker Scenario B). If active blocking of the presence signal itself is additionally required during this phase, APIX MUST return HTTP 401 with error code token_revoked — identical to a normal token rotation response. This response MUST NOT include any indication that the device has been identified as malicious.¶

• Consumer query endpoint: Response returned with an intentional processing delay of 2–10 seconds (configurable per entry). Results MAY be limited to high-trust entries only (org_level_min: O-2, service_level_min: S-2). No error is returned; the delay and filtering are silent.¶

• Logging: Enhanced, as per observe.¶

Tier 3 — block (law enforcement action taken or imminent; covert restriction no longer required):¶

• Presence endpoint: MUST return HTTP 401 with error code device_quarantined. This response explicitly signals that the device's APIX access has been administratively suspended. This tier MUST be activated in coordination with the relevant law enforcement authority and SHOULD be timed to coincide with or follow an enforcement action (arrest, infrastructure seizure, botnet takedown).¶

• Consumer query endpoint: MUST return HTTP 403. No result data returned.¶

• Logging: Full detail, with real-time alert to APIX operator security team.¶

Tier transitions MUST follow the direction observe → degrade → block. Downgrade (e.g., block to degrade) is permitted only by explicit operator authorisation with documented justification. Removal from the Bad-Bot Registry requires dual-control operator authorisation and is logged permanently in the tamper-evident audit log.¶

The existence of the Bad-Bot Registry and its aggregate statistics (total entries by tier, by source type, by jurisdiction) MUST be disclosed in the annual transparency report. Individual registry entries MUST NOT be disclosed publicly.¶

1.9.1. Additions to the APIX Protocol Type Registry

This document requests the following additions to the Protocol Type Registry maintained by the governing body at apix.example.org/registry/protocols:¶

1.9.2. APIX Presence Mode Registry

This document defines the initial contents of the APIX Presence Mode Registry, maintained by the governing body at apix.example.org/registry/presence-modes. Values in this registry MUST be used in the presence_mode field of device class APMs.¶

New values MAY be registered by the governing body through its registry extension process. Each new value MUST specify the trust ceiling it imposes and the conditions under which APIX can independently verify the signal's authenticity.¶

1.9.3. APIX Device Delegation Scope Registry

This document defines the initial contents of the APIX Device Delegation Scope Registry, maintained by the governing body at apix.example.org/registry/delegation-scopes. Values in this registry MUST be used in the scopes field of delegation grant requests (Section 6.3).¶

New scope values MAY be registered by the governing body. Each new scope MUST specify: the operations it permits, any prerequisite scopes, and whether it implies any data access beyond what is already visible in the device instance record.¶

1.9.4. Additions to the APIX Capability Taxonomy Registry

This document requests the following additions to the Capability Taxonomy Registry maintained by the governing body at apix.example.org/registry/capabilities:¶

1.10.1. Normative References

• [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.¶

• [RFC9110] Fielding, R., et al., "HTTP Semantics", RFC 9110, June 2022.¶

• [APIX-CORE] Rehfeld, C., "API Index (APIX): Core Infrastructure for Autonomous Agent Service Discovery", draft-rehfeld-apix-core-00.¶

1.10.2. Informative References

• [RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594, May 2019.¶

• [RFC9745] Cedik, A., et al., "The Deprecation HTTP Header Field", RFC 9745, March 2025.¶

• [APIX-SERVICES] Rehfeld, C., "APIX Services Profile: Discovery Infrastructure for Web API and Bot Services", draft-rehfeld-apix-services-00.¶