Skip to content
/
Report the server's host...
Last updated

Report the server's host key

Stores the server's own SSH host key (K1) after the client replaced the bootstrap host key (K0) on the server, and forgets the bootstrap key. From then on host_key_pub is the only key clients should trust and bootstrap_host_key_pub is null. The server's state does not change.

The bootstrap key's private half reached the server through the provider's metadata, so it must not stay trusted. While the server is in securing, the client — connected and pinned to bootstrap_host_key_pub — waits for /var/lib/forge/bootstrap.done, reads the staged key from /etc/ssh/forge_next_ed25519_key.pub and pins it, runs touch /var/lib/forge/host-key/commit so the server switches to it, reconnects pinned to K1, and then calls this endpoint. Mark a server ready is refused until it has.

Reporting the same key again returns the server unchanged; reporting a different key later replaces the stored one; reporting the bootstrap key itself is refused. Allowed while the server is awaiting_client, securing, installing or pairing.

Requires a bearer token (or API key) whose principal holds the use_forge capability in the acting organization and created the server or holds manage_forge, and Forge cloud compute switched on for the organization.

POSThttps://api.aitronos.com/v1/forge/compute/hosts/{host_id}/host-key

Path Parameters

host_id string required

The server's id: the fchost_ id returned in id, or the UUID sent when the server was created (any letter case, with or without hyphens).

Query Parameters

organization_id string optional

The organization the server belongs to: send its organization.id (from List your servers in every organization). Defaults to your current organization, where a server of another organization is not found. You must be an active member of it, or the request is refused with 403 ORGANIZATION_ACCESS_DENIED.

Headers

X-Organization-Id string optional

The same as organization_id, as a header. When both are sent, the query parameter wins.

Body Parameters

host_key_pub string required

The public half of the server's new host key, as one OpenSSH line: ssh-ed25519, ecdsa-sha2-nistp256/384/521, or ssh-rsa of 3072 to 16384 bits. Security-key types are refused because an SSH server cannot use them as host keys. No options prefix and no certificates; a comment is kept, reduced to letters, digits and @._-.

Unknown fields are refused.

Returns

200 OK with the server object: host_key_pub set, bootstrap_host_key_pub null.

{
  "id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90",
  "offering_id": "aitronos",
  "kind": "managed",
  "name": "build-box",
  "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"},
  "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7",
  "project_group": {"id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "client_id": "grp-clients", "name": "Clients"},
  "location_id": "eu-central",
  "location_label": "Germany",
  "size_id": "std-16",
  "size_label": "16 vCPU · 64 GB",
  "state": "securing",
  "state_label": "Securing the connection",
  "transient": true,
  "step": "securing",
  "step_started_at": "2026-09-28T09:01:20.118532Z",
  "state_changed_at": "2026-09-28T09:01:20.118532Z",
  "failure": null,
  "ipv4": "203.0.113.24",
  "ipv6": "2001:db8:4f2a::1",
  "ssh_port": 22,
  "ssh_user": "forge",
  "bootstrap_host_key_pub": null,
  "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000",
  "price": {
    "hourly": "0.83",
    "monthly_cap": "520.30",
    "currency": "CHF",
    "source": "aitronos",
    "includes_vat": false,
    "catalog_version": "fc-3b8e1f0a9c42",
    "quoted_at": "2026-09-28T09:00:00.184066Z",
    "parked_per_gb_month": "0.0269",
    "price_verified": true
  },
  "month_to_date": "0.83",
  "notice": null,
  "idle_reminder": null,
  "reconcile_flags": null,
  "actions": ["park", "delete", "revoke"],
  "created_at": "2026-09-28T09:00:00.184066Z",
  "ready_at": null,
  "parked_at": null,
  "parked_expires_at": null,
  "deleted_at": null,
  "revoked_at": null,
  "revoke_reason": null,
  "last_activity_at": null
}

Errors

StatusCodeWhen
401AUTHENTICATION_REQUIREDNo valid credential.
403ORGANIZATION_ACCESS_DENIEDorganization_id or X-Organization-Id names an organization you are not an active member of.
403INSUFFICIENT_PERMISSIONSThe caller does not hold use_forge in the acting organization.
403FORGE_COMPUTE_DISABLEDForge cloud compute is not switched on for the organization.
404FORGE_COMPUTE_HOST_NOT_FOUNDNo server with this id in the acting organization, or it was created by someone else and the caller does not hold manage_forge.
409FORGE_COMPUTE_INVALID_STATEThe server is not being set up. details.action is host_key.
422FORGE_COMPUTE_INVALID_HOST_KEYNot one accepted OpenSSH public key, or still the bootstrap key. details.reason says why.
422VALIDATION_ERRORhost_key_pub is missing or the body has an unknown field.
422INVALID_ID_FORMAThost_id is neither a UUID nor fchost_<32 hex>.
cURL
curl -X POST "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90/host-key" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000"
  }'

Response:

{
  "id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90",
  "offering_id": "aitronos",
  "kind": "managed",
  "name": "build-box",
  "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"},
  "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7",
  "project_group": {"id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "client_id": "grp-clients", "name": "Clients"},
  "location_id": "eu-central",
  "location_label": "Germany",
  "size_id": "std-16",
  "size_label": "16 vCPU · 64 GB",
  "state": "securing",
  "state_label": "Securing the connection",
  "transient": true,
  "step": "securing",
  "step_started_at": "2026-09-28T09:01:20.118532Z",
  "state_changed_at": "2026-09-28T09:01:20.118532Z",
  "failure": null,
  "ipv4": "203.0.113.24",
  "ipv6": "2001:db8:4f2a::1",
  "ssh_port": 22,
  "ssh_user": "forge",
  "bootstrap_host_key_pub": null,
  "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000",
  "price": {
    "hourly": "0.83",
    "monthly_cap": "520.30",
    "currency": "CHF",
    "source": "aitronos",
    "includes_vat": false,
    "catalog_version": "fc-3b8e1f0a9c42",
    "quoted_at": "2026-09-28T09:00:00.184066Z",
    "parked_per_gb_month": "0.0269",
    "price_verified": true
  },
  "month_to_date": "0.83",
  "notice": null,
  "idle_reminder": null,
  "reconcile_flags": null,
  "actions": ["park", "delete", "revoke"],
  "created_at": "2026-09-28T09:00:00.184066Z",
  "ready_at": null,
  "parked_at": null,
  "parked_expires_at": null,
  "deleted_at": null,
  "revoked_at": null,
  "revoke_reason": null,
  "last_activity_at": null
}
Previous page
Next page