Cloud API Reference — Outpost Lifecycle

The Cloud Outpost API manages the full lifecycle of Arbitex Hybrid Outpost nodes: registration, mTLS certificate issuance, certificate renewal, heartbeat telemetry, and deregistration. All management endpoints are served at https://cloud.arbitex.ai under the /v1/orgs router prefix.

This API is consumed by Arbitex operators and automation tooling. Deployed outpost processes use only the heartbeat endpoint during normal operation.

Authentication

Two authentication schemes are in use across this API.

Admin API key — required for all management operations (register, list, renew, deregister). Pass the key in the X-API-Key request header.

X-API-Key: arb_<your_admin_api_key>

Mutual TLS (mTLS) — used by deployed outpost processes to authenticate the heartbeat endpoint. In production, NGINX terminates TLS and forwards the verified client certificate as the X-SSL-Client-Cert header. During development or testing, an admin API key may be substituted instead.

PKI and certificates

Outpost client certificates are issued by Arbitex’s internal step-ca PKI at registration and renewal time.

Property	Value
Validity period	90 days
CN format	`outpost-{org_id}-{outpost_id}.arbitex.internal`
Key material	Private key returned once at issuance — never stored by Cloud

The client_cert, client_key, and ca_bundle fields in registration and renewal responses are returned exactly once. Store this material securely immediately; it cannot be retrieved again.

Schemas

`OutpostResponse`

Returned by all management endpoints. Does not include certificate material.

Field	Type	Description
`id`	string	Outpost UUID
`org_id`	string	Parent organization ID
`outpost_name`	string	Human-readable name assigned at registration
`region`	string	Deployment region label
`deployment_env`	string \| null	Customer VPC or cloud context string — informational only
`status`	string	`active`, `inactive`, `cert_expired`, or `deregistered`
`cert_issued_at`	datetime \| null	ISO 8601 timestamp of most recent certificate issuance
`cert_expires_at`	datetime \| null	ISO 8601 timestamp of current certificate expiry
`created_at`	datetime	ISO 8601 timestamp of outpost registration
`deregistered_at`	datetime \| null	ISO 8601 timestamp of deregistration, if applicable
`last_seen`	datetime \| null	ISO 8601 timestamp of most recent heartbeat received
`outpost_version`	string \| null	Outpost software version reported in last heartbeat
`policy_version`	string \| null	Policy bundle version reported in last heartbeat
`dlp_model_version`	string \| null	DLP model version reported in last heartbeat
`pending_audit_events`	integer \| null	Pending audit event count from last heartbeat
`tier3_active`	boolean \| null	Whether Tier 3 local AI processing was active at last heartbeat

`RegisterOutpostRequest`

Field	Type	Required	Constraints	Description
`outpost_name`	string	Yes	1–128 chars	Display name for this outpost
`region`	string	Yes	1–64 chars	Deployment region (e.g. `us-east-1`)
`deployment_env`	string \| null	No	max 255 chars	VPC name, cloud account ID, or other context

`HeartbeatRequest`

Field	Type	Required	Default	Description
`version`	string	Yes	—	Outpost software version (max 32 chars)
`uptime`	integer	Yes	—	Process uptime in seconds (≥ 0)
`policy_version`	string	No	`"none"`	Active policy bundle version (max 128 chars)
`last_sync_at`	datetime \| null	No	null	ISO 8601 timestamp of last policy sync
`dlp_model_version`	string	No	`"none"`	Active DLP model version (max 128 chars)
`pending_audit_events`	integer	No	`0`	Count of buffered audit events not yet flushed (≥ -1)
`tier3_active`	boolean	No	`false`	Whether Tier 3 local inference is currently active

`HeartbeatAck`

Field	Type	Description
`outpost_id`	string	ID of the outpost that sent the heartbeat
`received_at`	datetime	ISO 8601 server timestamp of receipt

Endpoints

Register Outpost

POST /v1/orgs/{org_id}/outposts

Registers a new Hybrid Outpost for the specified organization. On success, returns the outpost record together with a one-time mTLS certificate bundle. The private key is not stored by Cloud — if it is lost, the certificate must be renewed.

Authentication: Admin API key (X-API-Key)

Path parameters

Parameter	Description
`org_id`	Organization UUID

Request body — RegisterOutpostRequest

Field	Type	Required	Description
`outpost_name`	string	Yes	Display name (1–128 chars)
`region`	string	Yes	Deployment region label (1–64 chars)
`deployment_env`	string \| null	No	VPC or cloud environment context

Request

curl -X POST https://cloud.arbitex.ai/v1/orgs/org_01HZ_ACME/outposts \
  -H "X-API-Key: arb_your_admin_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "outpost_name": "acme-prod-us-east",
    "region": "us-east-1",
    "deployment_env": "vpc-0abc1234def567890"
  }'

Response 201 Created

{
  "outpost": {
    "id": "op_01HZ_PROD_USE1",
    "org_id": "org_01HZ_ACME",
    "outpost_name": "acme-prod-us-east",
    "region": "us-east-1",
    "deployment_env": "vpc-0abc1234def567890",
    "status": "active",
    "cert_issued_at": "2026-03-09T12:00:00Z",
    "cert_expires_at": "2026-06-07T12:00:00Z",
    "created_at": "2026-03-09T12:00:00Z",
    "deregistered_at": null,
    "last_seen": null,
    "outpost_version": null,
    "policy_version": null,
    "dlp_model_version": null,
    "pending_audit_events": null,
    "tier3_active": null
  },
  "client_cert": "-----BEGIN CERTIFICATE-----\nMIIB...base64...\n-----END CERTIFICATE-----\n",
  "client_key": "-----BEGIN EC PRIVATE KEY-----\nMIIB...base64...\n-----END EC PRIVATE KEY-----\n",
  "ca_bundle": "-----BEGIN CERTIFICATE-----\nMIIB...base64...\n-----END CERTIFICATE-----\n"
}

Error responses

Status	Description
`401`	Invalid or missing API key
`404`	Organization not found

List Outposts

GET /v1/orgs/{org_id}/outposts

Returns all outposts registered to the specified organization, including deregistered outposts.

Authentication: Admin API key (X-API-Key)

Path parameters

Parameter	Description
`org_id`	Organization UUID

Request

curl https://cloud.arbitex.ai/v1/orgs/org_01HZ_ACME/outposts \
  -H "X-API-Key: arb_your_admin_api_key"

Response 200 OK

[
  {
    "id": "op_01HZ_PROD_USE1",
    "org_id": "org_01HZ_ACME",
    "outpost_name": "acme-prod-us-east",
    "region": "us-east-1",
    "deployment_env": "vpc-0abc1234def567890",
    "status": "active",
    "cert_issued_at": "2026-03-09T12:00:00Z",
    "cert_expires_at": "2026-06-07T12:00:00Z",
    "created_at": "2026-03-09T12:00:00Z",
    "deregistered_at": null,
    "last_seen": "2026-03-09T14:58:00Z",
    "outpost_version": "1.4.2",
    "policy_version": "policy-bundle-v42",
    "dlp_model_version": "dlp-v3.1.0",
    "pending_audit_events": 0,
    "tier3_active": false
  },
  {
    "id": "op_01HZ_STAGING",
    "org_id": "org_01HZ_ACME",
    "outpost_name": "acme-staging",
    "region": "us-west-2",
    "deployment_env": null,
    "status": "deregistered",
    "cert_issued_at": "2026-01-15T09:00:00Z",
    "cert_expires_at": "2026-04-15T09:00:00Z",
    "created_at": "2026-01-15T09:00:00Z",
    "deregistered_at": "2026-02-28T16:30:00Z",
    "last_seen": "2026-02-28T16:00:00Z",
    "outpost_version": "1.3.8",
    "policy_version": "policy-bundle-v38",
    "dlp_model_version": "dlp-v3.0.1",
    "pending_audit_events": 4,
    "tier3_active": false
  }
]

Error responses

Status	Description
`401`	Invalid or missing API key
`404`	Organization not found

Deregister Outpost

DELETE /v1/orgs/{org_id}/outposts/{outpost_id}

Deregisters an outpost and immediately revokes its mTLS certificate via step-ca CRL. The outpost record is retained with status: deregistered. Deregistered outposts cannot send heartbeats or renew certificates.

Authentication: Admin API key (X-API-Key)

Path parameters

Parameter	Description
`org_id`	Organization UUID
`outpost_id`	Outpost UUID

Request

curl -X DELETE \
  "https://cloud.arbitex.ai/v1/orgs/org_01HZ_ACME/outposts/op_01HZ_STAGING" \
  -H "X-API-Key: arb_your_admin_api_key"

Response 204 No Content

No response body.

Side effects

The outpost certificate CN is added to the step-ca CRL.
Outpost status is set to deregistered and deregistered_at is stamped.
Subsequent heartbeats from the outpost are rejected with 409.

Error responses

Status	Description
`401`	Invalid or missing API key
`404`	Outpost or organization not found
`409`	Outpost is already deregistered

Renew Certificate

POST /v1/orgs/{org_id}/outposts/{outpost_id}/renew

Issues a new mTLS certificate for an active outpost. The new certificate bundle is returned once and must be stored immediately. The old certificate remains valid until its natural expiry (CRL grace period); there is no immediate revocation on renewal.

Renewal should be triggered before cert_expires_at to avoid heartbeat authentication failures. Automated renewal is recommended at 60 days into the 90-day validity window.

Authentication: Admin API key (X-API-Key)

Path parameters

Parameter	Description
`org_id`	Organization UUID
`outpost_id`	Outpost UUID

Request body

Empty body — no fields required.

Request

curl -X POST \
  "https://cloud.arbitex.ai/v1/orgs/org_01HZ_ACME/outposts/op_01HZ_PROD_USE1/renew" \
  -H "X-API-Key: arb_your_admin_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200 OK

{
  "outpost": {
    "id": "op_01HZ_PROD_USE1",
    "org_id": "org_01HZ_ACME",
    "outpost_name": "acme-prod-us-east",
    "region": "us-east-1",
    "deployment_env": "vpc-0abc1234def567890",
    "status": "active",
    "cert_issued_at": "2026-03-09T15:00:00Z",
    "cert_expires_at": "2026-06-07T15:00:00Z",
    "created_at": "2026-03-09T12:00:00Z",
    "deregistered_at": null,
    "last_seen": "2026-03-09T14:58:00Z",
    "outpost_version": "1.4.2",
    "policy_version": "policy-bundle-v42",
    "dlp_model_version": "dlp-v3.1.0",
    "pending_audit_events": 0,
    "tier3_active": false
  },
  "client_cert": "-----BEGIN CERTIFICATE-----\nMIIB...renewed-cert...\n-----END CERTIFICATE-----\n",
  "client_key": "-----BEGIN EC PRIVATE KEY-----\nMIIB...renewed-key...\n-----END EC PRIVATE KEY-----\n",
  "ca_bundle": "-----BEGIN CERTIFICATE-----\nMIIB...ca-bundle...\n-----END CERTIFICATE-----\n"
}

Error responses

Status	Description
`401`	Invalid or missing API key
`404`	Outpost or organization not found
`409`	Outpost is deregistered — renewal not permitted

Heartbeat

POST /v1/orgs/{org_id}/outposts/{outpost_id}/heartbeat

Receives a telemetry heartbeat from a deployed outpost. Heartbeats update the outpost’s last_seen timestamp and sync version/state fields on the OutpostResponse record. Outposts should send a heartbeat every 120 seconds.

Authentication: mTLS via X-SSL-Client-Cert header (production) or admin API key via X-API-Key (development and testing)

Path parameters

Parameter	Description
`org_id`	Organization UUID
`outpost_id`	Outpost UUID

Request body — HeartbeatRequest

Field	Type	Required	Default	Description
`version`	string	Yes	—	Outpost software version
`uptime`	integer	Yes	—	Process uptime in seconds
`policy_version`	string	No	`"none"`	Active policy bundle version
`last_sync_at`	datetime \| null	No	null	ISO 8601 timestamp of last policy sync
`dlp_model_version`	string	No	`"none"`	Active DLP model version
`pending_audit_events`	integer	No	`0`	Count of buffered audit events not yet flushed
`tier3_active`	boolean	No	`false`	Whether Tier 3 local inference is currently active

Request

# Production: mTLS via client cert (NGINX injects X-SSL-Client-Cert automatically)
# Development: use admin API key
curl -X POST \
  "https://cloud.arbitex.ai/v1/orgs/org_01HZ_ACME/outposts/op_01HZ_PROD_USE1/heartbeat" \
  -H "X-API-Key: arb_your_admin_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.4.2",
    "uptime": 86400,
    "policy_version": "policy-bundle-v42",
    "last_sync_at": "2026-03-09T14:55:00Z",
    "dlp_model_version": "dlp-v3.1.0",
    "pending_audit_events": 0,
    "tier3_active": false
  }'

Response 200 OK — HeartbeatAck

{
  "outpost_id": "op_01HZ_PROD_USE1",
  "received_at": "2026-03-09T15:00:00Z"
}

Error responses

Status	Description
`401`	Invalid or missing authentication (mTLS cert not verified, or API key invalid)
`404`	Outpost or organization not found
`409`	Outpost is deregistered — heartbeats not accepted

Outpost status values

Status	Description
`active`	Outpost is registered and its certificate is valid
`inactive`	Outpost has not sent a heartbeat within the expected window
`cert_expired`	Outpost certificate has passed `cert_expires_at` without renewal
`deregistered`	Outpost was explicitly deregistered; its certificate has been revoked via CRL

Certificate lifecycle

Registration
     |
     v
cert_issued_at ──────────────────────────────────────────── cert_expires_at (90 days)
                                          ^
                                          |
                              Recommended renewal window
                              (day 60 onward)
                                          |
                                     POST /renew
                                          |
                                          v
                               New cert_issued_at ─────────── New cert_expires_at (+90 days)
                               Old cert still valid until natural expiry (CRL grace period)

When an outpost is deregistered, the current certificate is added to the step-ca CRL immediately. The CRL grace period does not apply to deregistered outposts.

Error response format

All error responses use a standard envelope:

{
  "error": "not_found",
  "message": "Outpost op_01HZ_MISSING not found for org org_01HZ_ACME",
  "detail": null
}

Field	Type	Description
`error`	string	Machine-readable error code
`message`	string	Human-readable description
`detail`	string \| null	Additional context, if available

Common error codes

Status	`error` value	Applies to
`401`	`unauthorized`	All endpoints — invalid or missing `X-API-Key` or mTLS credential
`404`	`not_found`	Register, List, Deregister, Renew, Heartbeat — org or outpost does not exist
`409`	`conflict`	Deregister — already deregistered; Renew — deregistered outpost; Heartbeat — deregistered outpost

Cloud API Reference — Outpost Lifecycle

Authentication

PKI and certificates

Schemas

OutpostResponse

RegisterOutpostRequest

HeartbeatRequest

HeartbeatAck

Endpoints

Register Outpost

List Outposts

Deregister Outpost

Renew Certificate

Heartbeat

Outpost status values

Certificate lifecycle

Error response format

Common error codes

See also

`OutpostResponse`

`RegisterOutpostRequest`

`HeartbeatRequest`

`HeartbeatAck`