Registration API
Register self-hosted (Home) and linked (Link) agent installations. These endpoints are backend-only and support the Home and Link deployment modes alongside the default Cloud mode.
Home mode runs the agent container on your own hardware via Docker. Link mode connects an existing OpenClaw instance to the Agentbot platform. Cloud mode (the default) runs the agent on Agentbot infrastructure.
Install script
Returns the Home mode installation shell script. No authentication required. The response content type is text/plain.
This script automates the setup of a self-hosted agent container. Pipe it to your shell to begin the Home mode installation:
curl -sSL https://api.agentbot.raveculture.xyz/install | bash
Link script
Returns the Link mode setup shell script. No authentication required. The response content type is text/plain.
This script connects an existing OpenClaw instance to the Agentbot platform. Pipe it to your shell to begin the Link mode setup:
curl -sSL https://api.agentbot.raveculture.xyz/link | bash
Validate API key
Validates a bearer token by computing a SHA-256 hash of the raw key and looking it up in the api_keys database table. Raw keys are never stored or compared directly. No session authentication is required — the API key is passed in the Authorization header.
The web application’s
key validation endpoint uses a separate bcrypt-based lookup with the
sk_ prefix convention. The backend endpoint documented here uses SHA-256 hashing and does not require the
sk_ prefix.
| Header | Required | Description |
|---|
Authorization | Yes | Bearer token in the format Bearer YOUR_API_KEY |
Response
{
"valid": true,
"userId": "user-a1b2c3d4",
"plan": "solo",
"features": ["dashboard", "marketplace", "analytics"]
}
| Field | Type | Description |
|---|
valid | boolean | Whether the key is valid |
userId | string | User identifier |
plan | string | Current subscription plan (label, solo, collective, or network) |
features | string[] | List of features available to the user |
Errors
| Code | Description |
|---|
| 401 | Missing bearer token or key is invalid |
| 500 | Internal error during key validation |
Authentication
All registration endpoints use the backend authenticate middleware, which extracts user context from identity headers (x-user-email, x-user-id, x-user-role).
When the HMAC_SECRET environment variable is configured (falls back to INTERNAL_API_KEY), the middleware requires an additional x-user-signature header containing an HMAC-SHA256 signature of the identity payload. The frontend signs the string {userId}:{userEmail}:{userRole} with the shared secret.
| Header | Required | Description |
|---|
x-user-email | No | User email address. Defaults to empty string when omitted. |
x-user-id | No | User identifier. Defaults to anonymous when omitted. |
x-user-role | No | User role. Defaults to user when omitted. |
x-user-signature | Conditional | HMAC-SHA256 hex digest of {userId}:{userEmail}:{userRole}. Required when HMAC_SECRET is configured on the backend. |
When HMAC_SECRET is configured, requests without a valid x-user-signature header receive a 401 error with code SIGNATURE_REQUIRED. Requests with an invalid signature receive a 401 error with code INVALID_SIGNATURE.
Register Home installation
Registers a Home mode installation. Requires identity headers set by the authenticated frontend. See authentication above.
The web proxy forwards identity headers from the active session. The backend authenticate middleware reads these headers and attaches them to the request context. If no headers are provided, userId defaults to anonymous.
Request body
| Field | Type | Required | Description |
|---|
userId | string | Yes | User identifier |
mode | string | No | Deployment mode (defaults to home) |
gatewayToken | string | No | Gateway token for the installation |
Response
{
"success": true,
"message": "Home installation registered",
"dashboardUrl": "https://agentbot.raveculture.xyz/dashboard"
}
Errors
| Code | Description |
|---|
| 400 | userId is required |
| 500 | Internal server error |
Register Link installation
Registers a Link mode installation that connects an existing OpenClaw instance. Requires identity headers set by the authenticated frontend. See authentication above.
The web proxy forwards identity headers from the active session. The backend authenticate middleware reads these headers and attaches them to the request context. If no headers are provided, userId defaults to anonymous.
Request body
| Field | Type | Required | Description |
|---|
userId | string | Yes | User identifier |
gatewayToken | string | No | Gateway token for the linked instance |
Response
{
"success": true,
"message": "OpenClaw instance linked",
"dashboardUrl": "https://agentbot.raveculture.xyz/dashboard"
}
Errors
| Code | Description |
|---|
| 400 | userId is required |
| 500 | Internal server error |
List installations
Returns all registered installations across all deployment modes. Requires identity headers set by the authenticated frontend. See authentication above.
Response
{
"success": true,
"count": 2,
"installations": [
{
"user_id": "user-a1b2c3d4",
"mode": "home",
"registered_at": "2026-03-21T00:00:00Z",
"last_seen": "2026-03-21T12:00:00Z",
"status": "active"
},
{
"user_id": "user-e5f6g7h8",
"mode": "link",
"registered_at": "2026-03-21T01:00:00Z",
"last_seen": "2026-03-21T11:00:00Z",
"status": "active"
}
]
}
| Field | Type | Description |
|---|
installations[].user_id | string | User identifier |
installations[].mode | string | Deployment mode: home, link, or cloud |
installations[].registered_at | string | ISO 8601 timestamp of registration |
installations[].last_seen | string | ISO 8601 timestamp of last heartbeat |
installations[].status | string | Current status: active or inactive |
Errors
| Code | Description |
|---|
| 500 | Internal server error |
Registration heartbeat
Reports the status of a registered installation. When the userId matches a known registration, the last_seen timestamp is updated and the status is set to active. Requires authentication.
This is a backend registration heartbeat for Home and Link installations. It is separate from the
web heartbeat settings endpoint, which configures heartbeat scheduling for the web dashboard.
Endpoint authentication
This endpoint uses the authenticate middleware. See authentication above for the full header requirements including HMAC signature verification. When HMAC_SECRET is not configured, the middleware assigns default values (userId defaults to anonymous) and the request proceeds without rejecting unauthenticated requests.
Request body
| Field | Type | Required | Description |
|---|
userId | string | No | User identifier of the registered installation |
Response
{
"success": true,
"timestamp": "2026-03-21T12:00:00Z"
}
