Record a Wordwarden connector instance heartbeat.

POST

/api/auth/directory-connectors/heartbeat/{tenantId}/{connectorId}

Code sample: Shell / cURL

curl --request POST \
  --url https://auth.example.com/api/auth/directory-connectors/heartbeat/example/example \
  --header 'Content-Type: application/json' \
  --header 'X-Authrim-Heartbeat-Key-Id: example' \
  --header 'X-Authrim-Heartbeat-Signature: example' \
  --header 'X-Authrim-Heartbeat-Timestamp: example' \
  --data '{ "instance_id": "wwi_1234567890123456789012", "display_name": "campus-a", "transport": "direct", "version": "0.13.0", "release_channel": "stable", "started_at": "2026-06-24T00:00:00.000Z", "health_status": "healthy", "health_summary": { "ldap": "ok" }, "config_fingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "config_categories": [ "ldap" ], "drift_severity": "none" }'

Accepts a small HMAC-signed heartbeat from Authrim Wordwarden direct or tunnel transports. The heartbeat key is separate from the password verification key. The payload must not contain user PII, LDAP secrets, or raw LDAP internal values.

Parameters

Path Parameters

tenantId

required

string

>= 1 characters <= 128 characters

connectorId

required

string

/^wwcon_[a-zA-Z0-9]{16}$/

Header Parameters

X-Authrim-Heartbeat-Key-Id

required

string

<= 128 characters

X-Authrim-Heartbeat-Timestamp

required

string

Unix epoch milliseconds or ISO-8601 timestamp within the accepted clock skew.

X-Authrim-Heartbeat-Signature

required

string

/^(sha256=)?[a-fA-F0-9]{64}$/

Request Body ^required

Media type application/json

object

instance_id

required

Immutable Wordwarden instance identifier persisted in the connector state directory.

string

<= 128 characters /^[a-zA-Z0-9._:-]+$/

display_name

Human-readable operational display name. Not an identity boundary.

string

<= 128 characters

transport

required

string

Allowed values: relay direct tunnel

version

required

string

<= 64 characters

release_channel

string

default: stable <= 32 characters /^[a-zA-Z0-9_.-]{1,32}$/

started_at

required

string format: date-time

health_status

required

string

Allowed values: healthy degraded unhealthy

health_summary

Redacted operational health summary. Must not include PII, LDAP secrets, or LDAP internal values.

object

key

additional properties

config_fingerprint

required

string

/^sha256:[a-f0-9]{64}$/

config_categories

Array<string>

<= 32 items

drift_severity

string

default: none

Allowed values: none warning critical

key

additional properties

Example

{
  "instance_id": "wwi_1234567890123456789012",
  "display_name": "campus-a",
  "transport": "direct",
  "version": "0.13.0",
  "release_channel": "stable",
  "started_at": "2026-06-24T00:00:00.000Z",
  "health_status": "healthy",
  "health_summary": {
    "ldap": "ok"
  },
  "config_fingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "config_categories": [
    "ldap"
  ],
  "drift_severity": "none"
}

Responses

200

Heartbeat accepted.

Media type application/json

object

ok

required

boolean

status

required

string

Allowed values: connected unhealthy

instance_id

required

string

connector_id

required

string

/^wwcon_[a-zA-Z0-9]{16}$/

key

additional properties

Example

{
  "ok": true,
  "status": "connected",
  "instance_id": "wwi_1234567890123456789012",
  "connector_id": "wwcon_8K4M2Q9F7D3H6P1X"
}

400

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}

401

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}

403

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}

413

Error response.

Media type application/json

object

error

string

error_description

string

message

string

webauthn_signal

Optional browser-side WebAuthn Signal API hint. When unknown_credential is true, clients that just received a WebAuthn credential assertion may call PublicKeyCredential.signalUnknownCredential() for that credential ID.

object

unknown_credential

boolean

key

additional properties

Example ^generated

{
  "error": "example",
  "error_description": "example",
  "message": "example",
  "webauthn_signal": {
    "unknown_credential": true
  }
}