ApiSignal
Reference for the ApiSignal module: every class and function, with its full signature, parameters and return type. Signed session, channel and combined authentication tokens that the signal service verifies with a shared secret, deterministic channel ids, channel triggering, and the HTTP endpoint that issues a session token.
This page is a pure reference. Every token hash is the SHA-256 hex of the canonical JSON for the payload, a newline, and the shared secret; the shared secret is the signal service admin token. Only the classes and functions the module defines are listed here.
ApiSignal- signed session, channel and authentication tokens for the signal service, and channel triggering.ApiSignalApi- HTTP handlers for the ApiSignal API module.ApiSignalResultData- immutable data pairing a channel token with optional data.
ApiSignal
Static functions that build and hash signed tokens for signal WebSocket authentication, derive deterministic channel ids, and trigger signals. The functions are listed alphabetically.
BuildAuthenticationTokenData
ApiSignal::BuildAuthenticationTokenData(string $sessionId, string $channelIdHex32, int $ttlSeconds): object
Build a signed combined authentication token for a session and channel. Used as the WebSocket Authorization header, one token per channel connection.
| Name | Type | Description |
|---|---|---|
$sessionId | string | The PHP session id. |
$channelIdHex32 | string | A 32 hex character channel id. |
$ttlSeconds | int | Time-to-live in seconds, 1 to 86400. |
Returns object An object with sessionId, channelId, expiryTimestamp and hash.
BuildChannelTokenData
ApiSignal::BuildChannelTokenData(string $sessionId, string $channelIdHex32): object
Build a signed channel token: the session may listen on this channel. Used as the WebSocket toggle message body.
| Name | Type | Description |
|---|---|---|
$sessionId | string | The PHP session id. |
$channelIdHex32 | string | A 32 hex character channel id. |
Returns object An object with sessionId, channelId and hash.
BuildSessionTokenData
ApiSignal::BuildSessionTokenData(string $sessionId, int $ttlSeconds): object
Build a signed session token object for the current PHP session.
| Name | Type | Description |
|---|---|---|
$sessionId | string | The PHP session id. |
$ttlSeconds | int | Time-to-live in seconds, 1 to 86400. |
Returns object An object with sessionId, expiryTimestamp and hash.
CanonicalAuthenticationTokenJsonWithoutHash
ApiSignal::CanonicalAuthenticationTokenJsonWithoutHash(string $sessionId, string $channelIdHex32, int $expiryTimestamp): string
Build the canonical JSON without a hash for combined authentication token signing, with keys channelId, expiryTimestamp and sessionId sorted.
| Name | Type | Description |
|---|---|---|
$sessionId | string | The PHP session id. |
$channelIdHex32 | string | A 32 hex character channel id. |
$expiryTimestamp | int | Unix timestamp in seconds when the token expires. |
Returns string The canonical JSON.
CanonicalChannelTokenJsonWithoutHash
ApiSignal::CanonicalChannelTokenJsonWithoutHash(string $sessionId, string $channelIdHex32): string
Build the canonical JSON without a hash for channel token signing, with keys channelId and sessionId sorted.
| Name | Type | Description |
|---|---|---|
$sessionId | string | The PHP session id. |
$channelIdHex32 | string | A 32 hex character channel id. |
Returns string The canonical JSON.
CanonicalSessionTokenJsonWithoutHash
ApiSignal::CanonicalSessionTokenJsonWithoutHash(string $sessionId, int $expiryTimestamp): string
Build the canonical JSON without a hash for session token signing, with keys expiryTimestamp and sessionId sorted.
| Name | Type | Description |
|---|---|---|
$sessionId | string | The current PHP session id. |
$expiryTimestamp | int | Unix timestamp in seconds when the token expires. |
Returns string The canonical JSON.
ChannelIdForConfirmParts
ApiSignal::ChannelIdForConfirmParts(array $parts): string
A stable 32 character lowercase hex channel id from a JSON-encoded array of parts, where order matters. The same parts array always yields the same id; callers must use the same encoding.
| Name | Type | Description |
|---|---|---|
$parts | array | The ordered parts to encode as JSON. |
Returns string A 32 character lowercase hex channel id.
ChannelIdForScope
ApiSignal::ChannelIdForScope(string $scope): string
A stable 32 character lowercase hex channel id for a scope string, such as an endpoint plus parameters. The same scope string always yields the same id.
| Name | Type | Description |
|---|---|---|
$scope | string | The scope string to derive an id from. |
Returns string A 32 character lowercase hex channel id.
HashAuthenticationTokenPayload
ApiSignal::HashAuthenticationTokenPayload(object $payloadWithoutHash): string
The SHA-256 hex hash for a combined authentication token, from the sessionId, channelId and expiryTimestamp before the hash field is set.
| Name | Type | Description |
|---|---|---|
$payloadWithoutHash | object | An object with sessionId, channelId and expiryTimestamp. |
Returns string The SHA-256 hex hash.
HashChannelTokenPayload
ApiSignal::HashChannelTokenPayload(object $payloadWithoutHash): string
The SHA-256 hex hash for a channel token object, from the sessionId and channelId before the hash field is set.
| Name | Type | Description |
|---|---|---|
$payloadWithoutHash | object | An object with sessionId and channelId only. |
Returns string The SHA-256 hex hash.
HashSessionTokenPayload
ApiSignal::HashSessionTokenPayload(object $payloadWithoutHash): string
The SHA-256 hex hash for a session token payload (64 hex characters).
| Name | Type | Description |
|---|---|---|
$payloadWithoutHash | object | An object with sessionId and expiryTimestamp only. |
Returns string The SHA-256 hex hash.
SessionTokenTtlSeconds
ApiSignal::SessionTokenTtlSeconds(): int
The session token time-to-live in seconds, from the SESSION_TOKEN_TTL_SECONDS config value (default 600).
Returns int The time-to-live in seconds.
SharedSecret
ApiSignal::SharedSecret(): string
The shared secret aligned with the signal service admin token, read from the Cloud container database.
Returns string The shared secret.
Trigger
ApiSignal::Trigger(string $channelIdHex32): void
Trigger a real-time signal for subscribers on the given opaque channel id. Clients subscribed via the signed channel token for this id receive a notification.
| Name | Type | Description |
|---|---|---|
$channelIdHex32 | string | A 32 hex character channel id, the same id used to build the channel token or derived from a scope. |
Returns void
ApiSignalApi
HTTP handlers for the ApiSignal API module: endpoint registration and the session token handler. The functions are listed alphabetically.
Endpoints
ApiSignalApi::Endpoints(): void
Register the ApiSignal endpoints into the ApiConfig registry: the v1 module with the POST session.token endpoint.
Returns void
SessionToken
ApiSignalApi::SessionToken(object $input, ApiContext $ctx): object
Handle POST /api/ApiSignal/v1/session.token. Verifies the session proof matches the current session, then returns a signed session token. Throws an ApiErrorException with status 401 when the proof does not match.
| Name | Type | Description |
|---|---|---|
$input | object | The request body, with a sessionProofToken string matching the current session id. |
$ctx | ApiContext | The API request context. |
Returns object An object with sessionId, expiryTimestamp and hash.
ApiSignalResultData
Immutable data pairing a channel token with optional data. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$data->channelToken | string | The signed channel token (readonly). |
$data->optionalData | mixed | Any associated data (readonly). |
__construct
new ApiSignalResultData(string $channelToken, mixed $optionalData)
Create result data from a channel token and optional data.
| Name | Type | Description |
|---|---|---|
$channelToken | string | The signed channel token. |
$optionalData | mixed | Any associated data. |
Returns ApiSignalResultData