> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-api-spec-updates-1774886142.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Registration API

> Register and manage Home and Link mode installations

# 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.

<Note>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.</Note>

## Install script

```http theme={null}
GET /install
```

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:

```bash theme={null}
curl -sSL https://api.agentbot.raveculture.xyz/install | bash
```

## Link script

```http theme={null}
GET /link
```

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:

```bash theme={null}
curl -sSL https://api.agentbot.raveculture.xyz/link | bash
```

## Validate API key

```http theme={null}
POST /api/validate-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.

<Note>The web application's [key validation endpoint](/api-reference/keys#validate-key) 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.</Note>

### Headers

| Header          | Required | Description                                      |
| --------------- | -------- | ------------------------------------------------ |
| `Authorization` | Yes      | Bearer token in the format `Bearer YOUR_API_KEY` |

### Response

```json theme={null}
{
  "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. |

<Warning>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`.</Warning>

## Register Home installation

```http theme={null}
POST /api/register-home
```

Registers a Home mode installation. Requires identity headers set by the authenticated frontend. See [authentication](#authentication) above.

<Note>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`.</Note>

### 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

```json theme={null}
{
  "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

```http theme={null}
POST /api/register-link
```

Registers a Link mode installation that connects an existing OpenClaw instance. Requires identity headers set by the authenticated frontend. See [authentication](#authentication) above.

<Note>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`.</Note>

### Request body

| Field          | Type   | Required | Description                           |
| -------------- | ------ | -------- | ------------------------------------- |
| `userId`       | string | Yes      | User identifier                       |
| `gatewayToken` | string | No       | Gateway token for the linked instance |

### Response

```json theme={null}
{
  "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

```http theme={null}
GET /api/installations
```

Returns all registered installations across all deployment modes. Requires identity headers set by the authenticated frontend. See [authentication](#authentication) above.

### Response

```json theme={null}
{
  "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

```http theme={null}
POST /api/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.

<Note>This is a backend registration heartbeat for Home and Link installations. It is separate from the [web heartbeat settings](/api-reference/health#get-heartbeat-settings) endpoint, which configures heartbeat scheduling for the web dashboard.</Note>

### Endpoint authentication

This endpoint uses the `authenticate` middleware. See [authentication](#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

```json theme={null}
{
  "success": true,
  "timestamp": "2026-03-21T12:00:00Z"
}
```