Skip to main content

API Reference — Zeq-SSL

All endpoints are mounted under /api/ssl/* on the api-core daemon (default dev port :3099).

POST /api/ssl/credentials/issue​

Issue a fresh credential for a machine you administer.

Auth: ZeqAuth bearer / cookie + admin role on the target machine.

Body:

{ "machine": "<slug>", "mode": "A" | "B" }

Response 201:

{
  "ok": true,
  "credential": {
    "id": "<uuid>",
    "kid": "kid_xxxxxxxxxxxx",
    "pubkey_seed": "<64-hex>",
    "mode": "A",
    "issued_at_zeqond": 2287490000,
    "expires_at_zeqond": 2287621072,
    "row_fingerprint": "<64-hex>"
  },
  "secret_seed_hex": "<64-hex — shown ONCE>"
}

POST /api/ssl/credentials/rotate​

Rotate an existing credential. Old credential remains valid for SSL_GRACE_ZEQONDS = 128 Zeqonds.

Auth: admin on the credential's machine.

Body: { "credential_id": "<uuid>" }

Response 201: { ok, old_credential_id, new_credential: {...}, secret_seed_hex }

POST /api/ssl/credentials/revoke​

Revoke a credential. Effective immediately at the next Zeqond.

Auth: admin on the credential's machine.

Body:

{ "credential_id": "<uuid>", "reason": "unspecified|key_compromise|superseded|cessation_of_operation" }

Response 200: { ok, credential_id, revocation_id, revoked_at_zeqond }

GET /api/ssl/credentials?machine=<slug>​

List all credentials for a machine. Public — anyone can call.

Response 200: { machine, current_zeqond, credentials: [...] }

pubkey_seed is public; the secret seed is never on the wire.

POST /api/ssl/trust/grant​

Grant a trust edge.

Auth: admin on the truster machine.

Body:

{ "truster": "<slug>", "trusted": "<slug>", "trust_level": "basic|peer|federated" }

POST /api/ssl/trust/revoke​

Revoke a trust edge. Sets revoked_at_zeqond to now.

Auth: admin on the truster machine.

Body: { "truster": "<slug>", "trusted": "<slug>" }

GET /api/ssl/verify?machine=<slug>&kid=<kid>&zeqond=<n>​

Public verifier. Confirms a credential is valid at a specified Zeqond. zeqond is optional; omit for "right now".

Response 200:

{
  "machine": { "slug": "...", "id": "..." },
  "kid": "kid_xxxxxxxxxxxx",
  "zeqond": 2287490000,
  "valid": true,
  "reason": null,
  "credential": { "id", "pubkey_seed", "mode", "issued_at_zeqond", "expires_at_zeqond", "revoked_at_zeqond" }
}

POST /api/ssl/handshake/verify​

Server-side handshake validation. Used by Mode 2 bridges and external sidecar verifiers.

Body:

{
  "envelope": SignedHandshake,
  "local_machine": "<slug>",
  "peer_machine": "<slug>"
}

Response 200: { ok: true, derived_at_zeqond, local: {slug, kid}, peer: {slug, kid} }

Response 401: { ok: false, reason: "bad_mac" | "clock_skew" | "version_mismatch" | "suite_mismatch" | "peer_credential_invalid" | "local_credential_invalid" | "no_peer_seed" | "malformed" }

POST /api/ssl/peer-seed​

Mode B SSL-PEER-SEED-EXCHANGE helper. Store a derived shared seed in the operator's ZSC vault.

Auth: admin on local_machine.

Body: { "local_machine": "<slug>", "peer_machine": "<slug>", "shared_seed_hex": "<64-hex>" }