---
title: "REST API Reference"
description: "The WPSignal server API with cURL examples: auth, site registration, publish, WebSocket, SSE, and admin endpoints."
url: https://wpsignal.io/docs/api-reference/
---

# REST API Reference

Base URL: `https://api.wpsignal.io`

Live credentials (fill in to update all examples below)

API Key

Session JWT

Site Key

Publish Secret

### On this page

1.  [1\. Health Check](#health)
2.  [2\. Auth](#auth)
3.  [3\. Site Registration](#register)
4.  [4\. Dashboard](#dashboard)
5.  [5\. Publish](#publish)
6.  [6\. Dev Token](#dev-token)
7.  [7\. SSE](#sse)
8.  [8\. WebSocket](#websocket)
9.  [9\. Admin](#admin)

## 1\. Health Check

No authentication required. Confirms the server is reachable.

```
curl https://api.wpsignal.io/healthz
```

Returns: `{ "status": "ok" }`

## 2\. Auth

### Signup

Create a new account. Returns a session token and API key.

```
curl -s -X POST https://api.wpsignal.io/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"yourpassword"}'
```

Returns: `{ "token": "session_jwt", "api_key": "hex_string" }`

### Login

Authenticate with email and password.

```
curl -s -X POST https://api.wpsignal.io/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"yourpassword"}'
```

Returns: `{ "token": "session_jwt", "api_key": "hex_string" }`

### Get Current User

Verify a session token and retrieve account details.

```
curl -s https://api.wpsignal.io/auth/me \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

Returns: `{ "email": "...", "api_key": "...", "role": "user" }`

## 3\. Site Registration

Register a new site. Requires your API key from the dashboard. Create a free account at [wpsignal.io](https://api.wpsignal.io/dashboard/signup). Returns credentials that the WordPress plugin saves automatically.

```
curl -s -X POST https://api.wpsignal.io/api/sites/register \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"site_url":"https://example.com","site_name":"My Site"}'
```

Returns: `{ "site_key": "...", "publish_secret": "...", "jwt_secret": "..." }`

## 4\. Dashboard

### List My Sites

```
curl -s https://api.wpsignal.io/api/dashboard/sites \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

### Delete a Site

```
curl -s -X DELETE https://api.wpsignal.io/api/dashboard/sites/YOUR_SITE_KEY \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

### Regenerate API Key

```
curl -s -X POST https://api.wpsignal.io/api/dashboard/regenerate-key \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

Returns: `{ "api_key": "new_hex_string" }`

## 5\. Publish

Push an event to a channel. The request must be HMAC-SHA256 signed using your `publish_secret`. The signature covers `body + "." + timestamp_ms`.

```
SITE_KEY="YOUR_SITE_KEY"
SITE_SECRET="YOUR_PUBLISH_SECRET"
BODY='{"channel":"events","event":"post.updated","data":{"id":1,"title":"Hello"}}'
TIMESTAMP=$(date +%s%3N)
SIGNATURE=$(echo -n "${BODY}.${TIMESTAMP}" | openssl dgst -sha256 -hmac "$SITE_SECRET" | awk '{print $2}')

curl -s -X POST https://api.wpsignal.io/publish \
  -H 'Content-Type: application/json' \
  -H "x-wp-signal-key: $SITE_KEY" \
  -H "x-wp-signal-ts: $TIMESTAMP" \
  -H "x-wp-signal-sign: $SIGNATURE" \
  -d "$BODY"
```

Returns: `{ "ok": true }`

## 6\. Dev Token

Mint a short-lived connection JWT (30 minutes) for a site you hold the credentials for. The request carries the site's `publish_secret`, the same proof `/publish` demands, and the token can read and write every channel on that site. Intended for development, testing, and the [Explorer](https://wpsignal.io/docs/explorer/); in production the WordPress plugin mints its own tokens.

```
curl -s -X POST https://api.wpsignal.io/dev/token \
  -H 'Content-Type: application/json' \
  -d '{"site_key":"YOUR_SITE_KEY","publish_secret":"YOUR_PUBLISH_SECRET","user_id":"1","channels":["events"]}'
```

Returns: `{ "token": "connection_jwt", "channels": ["events"], "exp": 1234567890 }`. A missing or wrong secret is `401 invalid_secret`.

## 7\. SSE (Server-Sent Events)

Subscribe to channels over a persistent HTTP connection. Use `-N` to disable cURL buffering.

```
curl -s -N 'https://api.wpsignal.io/sse?token=YOUR_SESSION_JWT&channels=events'
```

Events are streamed in SSE format. The connection stays open until either side closes it. Use the connection JWT from [/dev/token](#dev-token) or the WordPress plugin's REST endpoint.

## 8\. WebSocket

The WebSocket transport is not directly usable with cURL. Use `websocat` for command-line testing.

```
websocat 'wss://api.wpsignal.io/ws?token=YOUR_SESSION_JWT'
```

### Client-to-server frames

| Frame | Example |
| --- | --- |
| subscribe | {"type":"subscribe","channels":\["events"\]} |
| unsubscribe | {"type":"unsubscribe","channels":\["events"\]} |
| auth | {"type":"auth","token":"new\_jwt"} |
| pong | {"type":"pong"} |

### Server-to-client frames

| Type | Description |
| --- | --- |
| message | Published event payload |
| subscribed | Confirmation of subscription |
| unsubscribed | Confirmation of unsubscription |
| auth\_ok | Token refresh accepted |
| ping | Keepalive sent every 20 seconds; respond with pong |
| error | Error details from the server |

## 9\. Admin

All admin endpoints require a session JWT with the `admin` role.

### List All Users

```
curl -s https://api.wpsignal.io/api/admin/users \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

### Delete a User

```
curl -s -X DELETE https://api.wpsignal.io/api/admin/users/USER_ID \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

### List All Sites

```
curl -s https://api.wpsignal.io/api/admin/sites \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

### Hub Stats

```
curl -s https://api.wpsignal.io/api/admin/stats \
  -H 'Authorization: Bearer YOUR_SESSION_JWT'
```

Returns: `{ "active_connections": 0, "published_messages": 0, "dropped_messages": 0, "total_users": 1, "total_sites": 1 }`

## Next steps

[

#### Getting Started

From a fresh WordPress install to live browser events in under 5 minutes.

](https://wpsignal.io/docs/getting-started/)[

#### PHP API

WPS facade, trigger builder, and WordPress filters.

](https://wpsignal.io/docs/php-api/)[

#### JS API

Subscribe, publish, and handle events from the browser.

](https://wpsignal.io/docs/js-api/)[

#### Explorer

Interactive playground: connect, publish, and inspect events live.

](https://wpsignal.io/docs/explorer/)