Hubfly spaceDocs
Console

Realtime API · Dashboard

Apps & keys

Create apps on a server, change their settings, and create, reveal, rotate or revoke their keys.

Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.

Realtime servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the realtime server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the realtime permissions must hold that exact permission.

How to use these endpoints

  1. Create an app per environment or product. Each app has its own channels, settings and keys.
  2. Read the app first: settings updates send its settingsRevision as revision, and a stale value returns 409 MANAGED_REALTIME_SETTINGS_CONFLICT.
  3. A new key's secret is returned in the create or rotate response and later only through an explicit, audited reveal. Rotate with graceSeconds so running servers can switch before the old key is revoked; bound projects get the new key automatically.

Create an app

curl
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/realtime/apps/create" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"web","settings":{"allowedOrigins":["https://example.com"],"clientEvents":false}}'

The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.

Endpoint reference

Dashboard endpoints (11)

These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.

Open interactive API explorer
POSTCreate a realtime appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/create

Create a Pusher-compatible app on this realtime server with its first key, optionally with initial settings. Returns the app, the key and the key's secret, plus a sync status that is pending while the server is stopped.

  • Requires realtime:admin.
  • The secret is returned once, with cache-control: no-store; read it again later with the key reveal call.
  • name is 1–64 printable characters and unique per server (409 MANAGED_REALTIME_APP_NAME_TAKEN); a server hosts up to 100 apps (409 MANAGED_REALTIME_APP_LIMIT).
  • Invalid settings return 400 MANAGED_REALTIME_INVALID_SETTINGS with an errors list of paths and messages.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
settingsobjectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "settings": {
      "type": "object",
      "properties": {
        "allowedOrigins": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "clientEvents": {
          "type": "boolean"
        },
        "subscriptionCountEvents": {
          "type": "boolean"
        },
        "requireUserAuthentication": {
          "type": "boolean"
        },
        "maxConnections": {
          "type": "number"
        },
        "maxChannelsPerConnection": {
          "type": "number"
        },
        "maxPresenceMembers": {
          "type": "number"
        },
        "maxMessageBytes": {
          "type": "number"
        },
        "maxPublishesPerSecond": {
          "type": "number"
        },
        "maxClientEventsPerSecond": {
          "type": "number"
        },
        "history": {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "off",
                "memory",
                "durable"
              ]
            },
            "ttlSeconds": {
              "type": "number"
            },
            "maxMessages": {
              "type": "number"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "sessions": {
          "type": "object",
          "properties": {
            "detachTtlSeconds": {
              "type": "number"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "offlineQueue": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "ttlSeconds": {
              "type": "number"
            },
            "maxMessages": {
              "type": "number"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "encryption": {
          "type": "string",
          "enum": [
            "off",
            "optional",
            "required"
          ]
        },
        "inspectorPayloadPreview": {
          "type": "boolean"
        }
      },
      "required": [],
      "additionalProperties": false
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "app": {
              "type": "object",
              "properties": {
                "appId": {
                  "type": "string"
                },
                "instanceId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "enabled": {
                  "type": "boolean"
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "user",
                    "ai_builder"
                  ]
                },
                "settings": {
                  "type": "object",
                  "properties": {
                    "allowedOrigins": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "clientEvents": {
                      "type": "boolean"
                    },
                    "subscriptionCountEvents": {
                      "type": "boolean"
                    },
                    "requireUserAuthentication": {
                      "type": "boolean"
                    },
                    "maxConnections": {
                      "type": "number"
                    },
                    "maxChannelsPerConnection": {
                      "type": "number"
                    },
                    "maxPresenceMembers": {
                      "type": "number"
                    },
                    "maxMessageBytes": {
                      "type": "number"
                    },
                    "maxPublishesPerSecond": {
                      "type": "number"
                    },
                    "maxClientEventsPerSecond": {
                      "type": "number"
                    },
                    "history": {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "off",
                            "memory",
                            "durable"
                          ]
                        },
                        "ttlSeconds": {
                          "type": "number"
                        },
                        "maxMessages": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "mode",
                        "ttlSeconds",
                        "maxMessages"
                      ],
                      "additionalProperties": false
                    },
                    "sessions": {
                      "type": "object",
                      "properties": {
                        "detachTtlSeconds": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "detachTtlSeconds"
                      ],
                      "additionalProperties": false
                    },
                    "offlineQueue": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "ttlSeconds": {
                          "type": "number"
                        },
                        "maxMessages": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "enabled",
                        "ttlSeconds",
                        "maxMessages"
                      ],
                      "additionalProperties": false
                    },
                    "encryption": {
                      "type": "string",
                      "enum": [
                        "off",
                        "optional",
                        "required"
                      ]
                    },
                    "inspectorPayloadPreview": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "allowedOrigins",
                    "clientEvents",
                    "subscriptionCountEvents",
                    "requireUserAuthentication",
                    "maxConnections",
                    "maxChannelsPerConnection",
                    "maxPresenceMembers",
                    "maxMessageBytes",
                    "maxPublishesPerSecond",
                    "maxClientEventsPerSecond",
                    "history",
                    "sessions",
                    "offlineQueue",
                    "encryption",
                    "inspectorPayloadPreview"
                  ],
                  "additionalProperties": false
                },
                "settingsRevision": {
                  "type": "number"
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "appId": {
                        "type": "string"
                      },
                      "key": {
                        "type": "string"
                      },
                      "secretHint": {
                        "type": "string"
                      },
                      "secretFingerprint": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "active",
                          "revoked",
                          "retiring"
                        ]
                      },
                      "expiresAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "revokedAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "lastRevealedAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Date string"
                      }
                    },
                    "required": [
                      "id",
                      "appId",
                      "key",
                      "secretHint",
                      "secretFingerprint",
                      "status",
                      "expiresAt",
                      "revokedAt",
                      "lastRevealedAt",
                      "createdAt"
                    ],
                    "additionalProperties": false
                  }
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "updatedAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "appId",
                "instanceId",
                "name",
                "enabled",
                "source",
                "settings",
                "settingsRevision",
                "keys",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            },
            "key": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "appId": {
                  "type": "string"
                },
                "key": {
                  "type": "string"
                },
                "secretHint": {
                  "type": "string"
                },
                "secretFingerprint": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "revoked",
                    "retiring"
                  ]
                },
                "expiresAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "revokedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastRevealedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "appId",
                "key",
                "secretHint",
                "secretFingerprint",
                "status",
                "expiresAt",
                "revokedAt",
                "lastRevealedAt",
                "createdAt"
              ],
              "additionalProperties": false
            },
            "secret": {
              "type": "string"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "status",
                "generation",
                "error"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "app",
            "key",
            "secret",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "app": {
          "appId": "string",
          "instanceId": "string",
          "name": "string",
          "enabled": true,
          "source": "user",
          "settings": {
            "allowedOrigins": [
              "string"
            ],
            "clientEvents": true,
            "subscriptionCountEvents": true,
            "requireUserAuthentication": true,
            "maxConnections": 0,
            "maxChannelsPerConnection": 0,
            "maxPresenceMembers": 0,
            "maxMessageBytes": 0,
            "maxPublishesPerSecond": 0,
            "maxClientEventsPerSecond": 0,
            "history": {
              "mode": "off",
              "ttlSeconds": 0,
              "maxMessages": 0
            },
            "sessions": {
              "detachTtlSeconds": 0
            },
            "offlineQueue": {
              "enabled": true,
              "ttlSeconds": 0,
              "maxMessages": 0
            },
            "encryption": "off",
            "inspectorPayloadPreview": true
          },
          "settingsRevision": 0,
          "keys": [
            {
              "id": "string",
              "appId": "string",
              "key": "string",
              "secretHint": "string",
              "secretFingerprint": "string",
              "status": "active",
              "expiresAt": "string",
              "revokedAt": "string",
              "lastRevealedAt": "string",
              "createdAt": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        },
        "key": {
          "id": "string",
          "appId": "string",
          "key": "string",
          "secretHint": "string",
          "secretFingerprint": "string",
          "status": "active",
          "expiresAt": "string",
          "revokedAt": "string",
          "lastRevealedAt": "string",
          "createdAt": "string"
        },
        "secret": "string",
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string"
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList realtime appsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps

List every app hosted on this realtime server, ordered by app ID, with its settings, settingsRevision and non-revoked keys. Keys show their public key, a secretHint and a secretFingerprint, never the secret.

  • Requires realtime:read.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "appId": {
                    "type": "string"
                  },
                  "instanceId": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "user",
                      "ai_builder"
                    ]
                  },
                  "settings": {
                    "type": "object",
                    "properties": {
                      "allowedOrigins": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "clientEvents": {
                        "type": "boolean"
                      },
                      "subscriptionCountEvents": {
                        "type": "boolean"
                      },
                      "requireUserAuthentication": {
                        "type": "boolean"
                      },
                      "maxConnections": {
                        "type": "number"
                      },
                      "maxChannelsPerConnection": {
                        "type": "number"
                      },
                      "maxPresenceMembers": {
                        "type": "number"
                      },
                      "maxMessageBytes": {
                        "type": "number"
                      },
                      "maxPublishesPerSecond": {
                        "type": "number"
                      },
                      "maxClientEventsPerSecond": {
                        "type": "number"
                      },
                      "history": {
                        "type": "object",
                        "properties": {
                          "mode": {
                            "type": "string",
                            "enum": [
                              "off",
                              "memory",
                              "durable"
                            ]
                          },
                          "ttlSeconds": {
                            "type": "number"
                          },
                          "maxMessages": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "mode",
                          "ttlSeconds",
                          "maxMessages"
                        ],
                        "additionalProperties": false
                      },
                      "sessions": {
                        "type": "object",
                        "properties": {
                          "detachTtlSeconds": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "detachTtlSeconds"
                        ],
                        "additionalProperties": false
                      },
                      "offlineQueue": {
                        "type": "object",
                        "properties": {
                          "enabled": {
                            "type": "boolean"
                          },
                          "ttlSeconds": {
                            "type": "number"
                          },
                          "maxMessages": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "enabled",
                          "ttlSeconds",
                          "maxMessages"
                        ],
                        "additionalProperties": false
                      },
                      "encryption": {
                        "type": "string",
                        "enum": [
                          "off",
                          "optional",
                          "required"
                        ]
                      },
                      "inspectorPayloadPreview": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "allowedOrigins",
                      "clientEvents",
                      "subscriptionCountEvents",
                      "requireUserAuthentication",
                      "maxConnections",
                      "maxChannelsPerConnection",
                      "maxPresenceMembers",
                      "maxMessageBytes",
                      "maxPublishesPerSecond",
                      "maxClientEventsPerSecond",
                      "history",
                      "sessions",
                      "offlineQueue",
                      "encryption",
                      "inspectorPayloadPreview"
                    ],
                    "additionalProperties": false
                  },
                  "settingsRevision": {
                    "type": "number"
                  },
                  "keys": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "appId": {
                          "type": "string"
                        },
                        "key": {
                          "type": "string"
                        },
                        "secretHint": {
                          "type": "string"
                        },
                        "secretFingerprint": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "active",
                            "revoked",
                            "retiring"
                          ]
                        },
                        "expiresAt": {
                          "type": "string",
                          "description": "Date string",
                          "nullable": true
                        },
                        "revokedAt": {
                          "type": "string",
                          "description": "Date string",
                          "nullable": true
                        },
                        "lastRevealedAt": {
                          "type": "string",
                          "description": "Date string",
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "Date string"
                        }
                      },
                      "required": [
                        "id",
                        "appId",
                        "key",
                        "secretHint",
                        "secretFingerprint",
                        "status",
                        "expiresAt",
                        "revokedAt",
                        "lastRevealedAt",
                        "createdAt"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "Date string"
                  },
                  "updatedAt": {
                    "type": "string",
                    "description": "Date string"
                  }
                },
                "required": [
                  "appId",
                  "instanceId",
                  "name",
                  "enabled",
                  "source",
                  "settings",
                  "settingsRevision",
                  "keys",
                  "createdAt",
                  "updatedAt"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "items"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "items": [
          {
            "appId": "string",
            "instanceId": "string",
            "name": "string",
            "enabled": true,
            "source": "user",
            "settings": {
              "allowedOrigins": [
                "string"
              ],
              "clientEvents": true,
              "subscriptionCountEvents": true,
              "requireUserAuthentication": true,
              "maxConnections": 0,
              "maxChannelsPerConnection": 0,
              "maxPresenceMembers": 0,
              "maxMessageBytes": 0,
              "maxPublishesPerSecond": 0,
              "maxClientEventsPerSecond": 0,
              "history": {
                "mode": "off",
                "ttlSeconds": 0,
                "maxMessages": 0
              },
              "sessions": {
                "detachTtlSeconds": 0
              },
              "offlineQueue": {
                "enabled": true,
                "ttlSeconds": 0,
                "maxMessages": 0
              },
              "encryption": "off",
              "inspectorPayloadPreview": true
            },
            "settingsRevision": 0,
            "keys": [
              {
                "id": "string",
                "appId": "string",
                "key": "string",
                "secretHint": "string",
                "secretFingerprint": "string",
                "status": "active",
                "expiresAt": "string",
                "revokedAt": "string",
                "lastRevealedAt": "string",
                "createdAt": "string"
              }
            ],
            "createdAt": "string",
            "updatedAt": "string"
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETEDelete a realtime appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/delete

Delete an app with its keys, webhooks and bindings, after removing the variables its bindings still own in connected projects. Open connections close with 4001 once the server applies the change, and the app ID is never reused.

  • Requires realtime:admin.
  • confirmName must equal the app name exactly, else 400 MANAGED_CONFIRMATION_MISMATCH.
  • Returns variablesRemoved, the number of environment variables deleted from bound projects.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
confirmNamequeryYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "deleted": {
              "const": true,
              "type": "boolean"
            },
            "variablesRemoved": {
              "type": "number"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "status",
                "generation",
                "error"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "deleted",
            "variablesRemoved",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "deleted": true,
        "variablesRemoved": 0,
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string"
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETRead a realtime appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId

Return one app with its name, enabled state, source, full settings, settingsRevision and non-revoked keys. Pass settingsRevision back as revision when you update the settings.

  • Requires realtime:read.
  • Unknown app: 404 MANAGED_REALTIME_APP_NOT_FOUND.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "appId": {
              "type": "string"
            },
            "instanceId": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "enabled": {
              "type": "boolean"
            },
            "source": {
              "type": "string",
              "enum": [
                "user",
                "ai_builder"
              ]
            },
            "settings": {
              "type": "object",
              "properties": {
                "allowedOrigins": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "clientEvents": {
                  "type": "boolean"
                },
                "subscriptionCountEvents": {
                  "type": "boolean"
                },
                "requireUserAuthentication": {
                  "type": "boolean"
                },
                "maxConnections": {
                  "type": "number"
                },
                "maxChannelsPerConnection": {
                  "type": "number"
                },
                "maxPresenceMembers": {
                  "type": "number"
                },
                "maxMessageBytes": {
                  "type": "number"
                },
                "maxPublishesPerSecond": {
                  "type": "number"
                },
                "maxClientEventsPerSecond": {
                  "type": "number"
                },
                "history": {
                  "type": "object",
                  "properties": {
                    "mode": {
                      "type": "string",
                      "enum": [
                        "off",
                        "memory",
                        "durable"
                      ]
                    },
                    "ttlSeconds": {
                      "type": "number"
                    },
                    "maxMessages": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "mode",
                    "ttlSeconds",
                    "maxMessages"
                  ],
                  "additionalProperties": false
                },
                "sessions": {
                  "type": "object",
                  "properties": {
                    "detachTtlSeconds": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "detachTtlSeconds"
                  ],
                  "additionalProperties": false
                },
                "offlineQueue": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "ttlSeconds": {
                      "type": "number"
                    },
                    "maxMessages": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "enabled",
                    "ttlSeconds",
                    "maxMessages"
                  ],
                  "additionalProperties": false
                },
                "encryption": {
                  "type": "string",
                  "enum": [
                    "off",
                    "optional",
                    "required"
                  ]
                },
                "inspectorPayloadPreview": {
                  "type": "boolean"
                }
              },
              "required": [
                "allowedOrigins",
                "clientEvents",
                "subscriptionCountEvents",
                "requireUserAuthentication",
                "maxConnections",
                "maxChannelsPerConnection",
                "maxPresenceMembers",
                "maxMessageBytes",
                "maxPublishesPerSecond",
                "maxClientEventsPerSecond",
                "history",
                "sessions",
                "offlineQueue",
                "encryption",
                "inspectorPayloadPreview"
              ],
              "additionalProperties": false
            },
            "settingsRevision": {
              "type": "number"
            },
            "keys": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "appId": {
                    "type": "string"
                  },
                  "key": {
                    "type": "string"
                  },
                  "secretHint": {
                    "type": "string"
                  },
                  "secretFingerprint": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "revoked",
                      "retiring"
                    ]
                  },
                  "expiresAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "revokedAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "lastRevealedAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "Date string"
                  }
                },
                "required": [
                  "id",
                  "appId",
                  "key",
                  "secretHint",
                  "secretFingerprint",
                  "status",
                  "expiresAt",
                  "revokedAt",
                  "lastRevealedAt",
                  "createdAt"
                ],
                "additionalProperties": false
              }
            },
            "createdAt": {
              "type": "string",
              "description": "Date string"
            },
            "updatedAt": {
              "type": "string",
              "description": "Date string"
            }
          },
          "required": [
            "appId",
            "instanceId",
            "name",
            "enabled",
            "source",
            "settings",
            "settingsRevision",
            "keys",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "appId": "string",
        "instanceId": "string",
        "name": "string",
        "enabled": true,
        "source": "user",
        "settings": {
          "allowedOrigins": [
            "string"
          ],
          "clientEvents": true,
          "subscriptionCountEvents": true,
          "requireUserAuthentication": true,
          "maxConnections": 0,
          "maxChannelsPerConnection": 0,
          "maxPresenceMembers": 0,
          "maxMessageBytes": 0,
          "maxPublishesPerSecond": 0,
          "maxClientEventsPerSecond": 0,
          "history": {
            "mode": "off",
            "ttlSeconds": 0,
            "maxMessages": 0
          },
          "sessions": {
            "detachTtlSeconds": 0
          },
          "offlineQueue": {
            "enabled": true,
            "ttlSeconds": 0,
            "maxMessages": 0
          },
          "encryption": "off",
          "inspectorPayloadPreview": true
        },
        "settingsRevision": 0,
        "keys": [
          {
            "id": "string",
            "appId": "string",
            "key": "string",
            "secretHint": "string",
            "secretFingerprint": "string",
            "status": "active",
            "expiresAt": "string",
            "revokedAt": "string",
            "lastRevealedAt": "string",
            "createdAt": "string"
          }
        ],
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTCreate an app keyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/keys/create

Add a new active key to an app and return it with its secret. Existing keys keep working.

  • Requires realtime:admin.
  • The secret is returned once, with cache-control: no-store.
  • An app holds up to 10 non-revoked keys: 409 MANAGED_REALTIME_KEY_LIMIT.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "key": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "appId": {
                  "type": "string"
                },
                "key": {
                  "type": "string"
                },
                "secretHint": {
                  "type": "string"
                },
                "secretFingerprint": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "revoked",
                    "retiring"
                  ]
                },
                "expiresAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "revokedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastRevealedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "appId",
                "key",
                "secretHint",
                "secretFingerprint",
                "status",
                "expiresAt",
                "revokedAt",
                "lastRevealedAt",
                "createdAt"
              ],
              "additionalProperties": false
            },
            "secret": {
              "type": "string"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "status",
                "generation",
                "error"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "key",
            "secret",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "key": {
          "id": "string",
          "appId": "string",
          "key": "string",
          "secretHint": "string",
          "secretFingerprint": "string",
          "status": "active",
          "expiresAt": "string",
          "revokedAt": "string",
          "lastRevealedAt": "string",
          "createdAt": "string"
        },
        "secret": "string",
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string"
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList app keysDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/keys

List all keys of an app, newest first, including retiring and revoked ones. Each key shows its public key, status, expiresAt for retiring keys, secretHint and secretFingerprint, never the secret.

  • Requires realtime:read.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "appId": {
                    "type": "string"
                  },
                  "key": {
                    "type": "string"
                  },
                  "secretHint": {
                    "type": "string"
                  },
                  "secretFingerprint": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "revoked",
                      "retiring"
                    ]
                  },
                  "expiresAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "revokedAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "lastRevealedAt": {
                    "type": "string",
                    "description": "Date string",
                    "nullable": true
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "Date string"
                  }
                },
                "required": [
                  "id",
                  "appId",
                  "key",
                  "secretHint",
                  "secretFingerprint",
                  "status",
                  "expiresAt",
                  "revokedAt",
                  "lastRevealedAt",
                  "createdAt"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "items"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "items": [
          {
            "id": "string",
            "appId": "string",
            "key": "string",
            "secretHint": "string",
            "secretFingerprint": "string",
            "status": "active",
            "expiresAt": "string",
            "revokedAt": "string",
            "lastRevealedAt": "string",
            "createdAt": "string"
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTReveal a key secretDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/keys/:keyId/reveal

Return the secret of an active or retiring key together with its key and appId. Every reveal is recorded in the audit log and updates the key's lastRevealedAt.

  • Requires realtime:admin.
  • The response carries a secret and is sent with cache-control: no-store.
  • A revoked key has no secret: 409 MANAGED_REALTIME_KEY_REVOKED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
keyIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "keyId": {
              "type": "string"
            },
            "appId": {
              "type": "string"
            },
            "key": {
              "type": "string"
            },
            "secret": {
              "type": "string"
            }
          },
          "required": [
            "keyId",
            "appId",
            "key",
            "secret"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "keyId": "string",
        "appId": "string",
        "key": "string",
        "secret": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRevoke an app keyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/keys/:keyId/revoke

Revoke an active or retiring key now and delete its secret. Connections using it close with 4001 once the server applies the change, and bound projects that used it are switched to the app's newest active key.

  • Requires realtime:admin.
  • The app's last active key cannot be revoked: 409 MANAGED_REALTIME_LAST_KEY. Create or rotate a key first, or disable the app.
  • Revoking an already revoked key succeeds without changes.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
keyIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "key": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "appId": {
                  "type": "string"
                },
                "key": {
                  "type": "string"
                },
                "secretHint": {
                  "type": "string"
                },
                "secretFingerprint": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "revoked",
                    "retiring"
                  ]
                },
                "expiresAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "revokedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastRevealedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "appId",
                "key",
                "secretHint",
                "secretFingerprint",
                "status",
                "expiresAt",
                "revokedAt",
                "lastRevealedAt",
                "createdAt"
              ],
              "additionalProperties": false
            },
            "appsUpdated": {
              "type": "number"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "status",
                "generation",
                "error"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "key",
            "appsUpdated",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "key": {
          "id": "string",
          "appId": "string",
          "key": "string",
          "secretHint": "string",
          "secretFingerprint": "string",
          "status": "active",
          "expiresAt": "string",
          "revokedAt": "string",
          "lastRevealedAt": "string",
          "createdAt": "string"
        },
        "appsUpdated": 0,
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string"
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTRotate an app keyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/keys/:keyId/rotate

Create a replacement active key and mark the old one retiring; the old key keeps working for graceSeconds, then is revoked automatically. Bound projects that used the old key get the new key and secret written into their variables.

  • Requires realtime:admin.
  • The new secret is returned once, with cache-control: no-store.
  • graceSeconds is 0 to 2,592,000 (30 days), default 86,400; out of range returns 400 MANAGED_REALTIME_INVALID_GRACE.
  • Only active keys rotate (409 MANAGED_REALTIME_KEY_NOT_ACTIVE); the new key counts toward the 10-key limit (409 MANAGED_REALTIME_KEY_LIMIT).
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
keyIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
graceSecondsnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "graceSeconds": {
      "type": "number"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "key": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "appId": {
                  "type": "string"
                },
                "key": {
                  "type": "string"
                },
                "secretHint": {
                  "type": "string"
                },
                "secretFingerprint": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "revoked",
                    "retiring"
                  ]
                },
                "expiresAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "revokedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastRevealedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "appId",
                "key",
                "secretHint",
                "secretFingerprint",
                "status",
                "expiresAt",
                "revokedAt",
                "lastRevealedAt",
                "createdAt"
              ],
              "additionalProperties": false
            },
            "secret": {
              "type": "string"
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "status",
                "generation",
                "error"
              ],
              "additionalProperties": false
            },
            "retiring": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "appId": {
                  "type": "string"
                },
                "key": {
                  "type": "string"
                },
                "secretHint": {
                  "type": "string"
                },
                "secretFingerprint": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "revoked",
                    "retiring"
                  ]
                },
                "expiresAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "revokedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "lastRevealedAt": {
                  "type": "string",
                  "description": "Date string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "id",
                "appId",
                "key",
                "secretHint",
                "secretFingerprint",
                "status",
                "expiresAt",
                "revokedAt",
                "lastRevealedAt",
                "createdAt"
              ],
              "additionalProperties": false
            },
            "appsUpdated": {
              "type": "number"
            }
          },
          "required": [
            "key",
            "secret",
            "sync",
            "retiring",
            "appsUpdated"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "key": {
          "id": "string",
          "appId": "string",
          "key": "string",
          "secretHint": "string",
          "secretFingerprint": "string",
          "status": "active",
          "expiresAt": "string",
          "revokedAt": "string",
          "lastRevealedAt": "string",
          "createdAt": "string"
        },
        "secret": "string",
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string"
        },
        "retiring": {
          "id": "string",
          "appId": "string",
          "key": "string",
          "secretHint": "string",
          "secretFingerprint": "string",
          "status": "active",
          "expiresAt": "string",
          "revokedAt": "string",
          "lastRevealedAt": "string",
          "createdAt": "string"
        },
        "appsUpdated": 0
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
PUTUpdate app settingsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/settings/update

Apply a partial settings update (allowed origins, client events, limits, history, sessions, offline queue, encryption policy, inspector previews). Omitted settings keep their value; changes apply to new messages and connections without a restart.

  • Requires realtime:admin.
  • Send revision equal to the app's current settingsRevision; if the settings changed meanwhile you get 409 MANAGED_REALTIME_SETTINGS_CONFLICT. A successful update increments the revision.
  • Unknown keys or out-of-range values return 400 MANAGED_REALTIME_INVALID_SETTINGS with an errors list; a no-op returns 400 MANAGED_REALTIME_APP_UNCHANGED.
  • allowedOrigins takes up to 50 entries: * alone, https://host[:port], http://localhost[:port] or https://*.domain.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
settingsobjectYes
revisionnumberYes
Complete request schema
{
  "type": "object",
  "properties": {
    "settings": {
      "type": "object",
      "properties": {
        "allowedOrigins": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "clientEvents": {
          "type": "boolean"
        },
        "subscriptionCountEvents": {
          "type": "boolean"
        },
        "requireUserAuthentication": {
          "type": "boolean"
        },
        "maxConnections": {
          "type": "number"
        },
        "maxChannelsPerConnection": {
          "type": "number"
        },
        "maxPresenceMembers": {
          "type": "number"
        },
        "maxMessageBytes": {
          "type": "number"
        },
        "maxPublishesPerSecond": {
          "type": "number"
        },
        "maxClientEventsPerSecond": {
          "type": "number"
        },
        "history": {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "off",
                "memory",
                "durable"
              ]
            },
            "ttlSeconds": {
              "type": "number"
            },
            "maxMessages": {
              "type": "number"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "sessions": {
          "type": "object",
          "properties": {
            "detachTtlSeconds": {
              "type": "number"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "offlineQueue": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "ttlSeconds": {
              "type": "number"
            },
            "maxMessages": {
              "type": "number"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "encryption": {
          "type": "string",
          "enum": [
            "off",
            "optional",
            "required"
          ]
        },
        "inspectorPayloadPreview": {
          "type": "boolean"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "revision": {
      "type": "number"
    }
  },
  "required": [
    "settings",
    "revision"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "app": {
              "type": "object",
              "properties": {
                "appId": {
                  "type": "string"
                },
                "instanceId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "enabled": {
                  "type": "boolean"
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "user",
                    "ai_builder"
                  ]
                },
                "settings": {
                  "type": "object",
                  "properties": {
                    "allowedOrigins": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "clientEvents": {
                      "type": "boolean"
                    },
                    "subscriptionCountEvents": {
                      "type": "boolean"
                    },
                    "requireUserAuthentication": {
                      "type": "boolean"
                    },
                    "maxConnections": {
                      "type": "number"
                    },
                    "maxChannelsPerConnection": {
                      "type": "number"
                    },
                    "maxPresenceMembers": {
                      "type": "number"
                    },
                    "maxMessageBytes": {
                      "type": "number"
                    },
                    "maxPublishesPerSecond": {
                      "type": "number"
                    },
                    "maxClientEventsPerSecond": {
                      "type": "number"
                    },
                    "history": {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "off",
                            "memory",
                            "durable"
                          ]
                        },
                        "ttlSeconds": {
                          "type": "number"
                        },
                        "maxMessages": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "mode",
                        "ttlSeconds",
                        "maxMessages"
                      ],
                      "additionalProperties": false
                    },
                    "sessions": {
                      "type": "object",
                      "properties": {
                        "detachTtlSeconds": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "detachTtlSeconds"
                      ],
                      "additionalProperties": false
                    },
                    "offlineQueue": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "ttlSeconds": {
                          "type": "number"
                        },
                        "maxMessages": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "enabled",
                        "ttlSeconds",
                        "maxMessages"
                      ],
                      "additionalProperties": false
                    },
                    "encryption": {
                      "type": "string",
                      "enum": [
                        "off",
                        "optional",
                        "required"
                      ]
                    },
                    "inspectorPayloadPreview": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "allowedOrigins",
                    "clientEvents",
                    "subscriptionCountEvents",
                    "requireUserAuthentication",
                    "maxConnections",
                    "maxChannelsPerConnection",
                    "maxPresenceMembers",
                    "maxMessageBytes",
                    "maxPublishesPerSecond",
                    "maxClientEventsPerSecond",
                    "history",
                    "sessions",
                    "offlineQueue",
                    "encryption",
                    "inspectorPayloadPreview"
                  ],
                  "additionalProperties": false
                },
                "settingsRevision": {
                  "type": "number"
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "appId": {
                        "type": "string"
                      },
                      "key": {
                        "type": "string"
                      },
                      "secretHint": {
                        "type": "string"
                      },
                      "secretFingerprint": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "active",
                          "revoked",
                          "retiring"
                        ]
                      },
                      "expiresAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "revokedAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "lastRevealedAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Date string"
                      }
                    },
                    "required": [
                      "id",
                      "appId",
                      "key",
                      "secretHint",
                      "secretFingerprint",
                      "status",
                      "expiresAt",
                      "revokedAt",
                      "lastRevealedAt",
                      "createdAt"
                    ],
                    "additionalProperties": false
                  }
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "updatedAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "appId",
                "instanceId",
                "name",
                "enabled",
                "source",
                "settings",
                "settingsRevision",
                "keys",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "status",
                "generation",
                "error"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "app",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "app": {
          "appId": "string",
          "instanceId": "string",
          "name": "string",
          "enabled": true,
          "source": "user",
          "settings": {
            "allowedOrigins": [
              "string"
            ],
            "clientEvents": true,
            "subscriptionCountEvents": true,
            "requireUserAuthentication": true,
            "maxConnections": 0,
            "maxChannelsPerConnection": 0,
            "maxPresenceMembers": 0,
            "maxMessageBytes": 0,
            "maxPublishesPerSecond": 0,
            "maxClientEventsPerSecond": 0,
            "history": {
              "mode": "off",
              "ttlSeconds": 0,
              "maxMessages": 0
            },
            "sessions": {
              "detachTtlSeconds": 0
            },
            "offlineQueue": {
              "enabled": true,
              "ttlSeconds": 0,
              "maxMessages": 0
            },
            "encryption": "off",
            "inspectorPayloadPreview": true
          },
          "settingsRevision": 0,
          "keys": [
            {
              "id": "string",
              "appId": "string",
              "key": "string",
              "secretHint": "string",
              "secretFingerprint": "string",
              "status": "active",
              "expiresAt": "string",
              "revokedAt": "string",
              "lastRevealedAt": "string",
              "createdAt": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        },
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string"
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
PUTRename or toggle an appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/update

Change an app's name or enabled state. Disabling an app closes its connections with close code 4003 once the server applies the change; enabling it accepts connections again.

  • Requires realtime:admin.
  • A request that changes nothing returns 400 MANAGED_REALTIME_APP_UNCHANGED; a duplicate name returns 409 MANAGED_REALTIME_APP_NAME_TAKEN.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringNo
enabledbooleanNo
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "app": {
              "type": "object",
              "properties": {
                "appId": {
                  "type": "string"
                },
                "instanceId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "enabled": {
                  "type": "boolean"
                },
                "source": {
                  "type": "string",
                  "enum": [
                    "user",
                    "ai_builder"
                  ]
                },
                "settings": {
                  "type": "object",
                  "properties": {
                    "allowedOrigins": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "clientEvents": {
                      "type": "boolean"
                    },
                    "subscriptionCountEvents": {
                      "type": "boolean"
                    },
                    "requireUserAuthentication": {
                      "type": "boolean"
                    },
                    "maxConnections": {
                      "type": "number"
                    },
                    "maxChannelsPerConnection": {
                      "type": "number"
                    },
                    "maxPresenceMembers": {
                      "type": "number"
                    },
                    "maxMessageBytes": {
                      "type": "number"
                    },
                    "maxPublishesPerSecond": {
                      "type": "number"
                    },
                    "maxClientEventsPerSecond": {
                      "type": "number"
                    },
                    "history": {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "off",
                            "memory",
                            "durable"
                          ]
                        },
                        "ttlSeconds": {
                          "type": "number"
                        },
                        "maxMessages": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "mode",
                        "ttlSeconds",
                        "maxMessages"
                      ],
                      "additionalProperties": false
                    },
                    "sessions": {
                      "type": "object",
                      "properties": {
                        "detachTtlSeconds": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "detachTtlSeconds"
                      ],
                      "additionalProperties": false
                    },
                    "offlineQueue": {
                      "type": "object",
                      "properties": {
                        "enabled": {
                          "type": "boolean"
                        },
                        "ttlSeconds": {
                          "type": "number"
                        },
                        "maxMessages": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "enabled",
                        "ttlSeconds",
                        "maxMessages"
                      ],
                      "additionalProperties": false
                    },
                    "encryption": {
                      "type": "string",
                      "enum": [
                        "off",
                        "optional",
                        "required"
                      ]
                    },
                    "inspectorPayloadPreview": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "allowedOrigins",
                    "clientEvents",
                    "subscriptionCountEvents",
                    "requireUserAuthentication",
                    "maxConnections",
                    "maxChannelsPerConnection",
                    "maxPresenceMembers",
                    "maxMessageBytes",
                    "maxPublishesPerSecond",
                    "maxClientEventsPerSecond",
                    "history",
                    "sessions",
                    "offlineQueue",
                    "encryption",
                    "inspectorPayloadPreview"
                  ],
                  "additionalProperties": false
                },
                "settingsRevision": {
                  "type": "number"
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "appId": {
                        "type": "string"
                      },
                      "key": {
                        "type": "string"
                      },
                      "secretHint": {
                        "type": "string"
                      },
                      "secretFingerprint": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "active",
                          "revoked",
                          "retiring"
                        ]
                      },
                      "expiresAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "revokedAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "lastRevealedAt": {
                        "type": "string",
                        "description": "Date string",
                        "nullable": true
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Date string"
                      }
                    },
                    "required": [
                      "id",
                      "appId",
                      "key",
                      "secretHint",
                      "secretFingerprint",
                      "status",
                      "expiresAt",
                      "revokedAt",
                      "lastRevealedAt",
                      "createdAt"
                    ],
                    "additionalProperties": false
                  }
                },
                "createdAt": {
                  "type": "string",
                  "description": "Date string"
                },
                "updatedAt": {
                  "type": "string",
                  "description": "Date string"
                }
              },
              "required": [
                "appId",
                "instanceId",
                "name",
                "enabled",
                "source",
                "settings",
                "settingsRevision",
                "keys",
                "createdAt",
                "updatedAt"
              ],
              "additionalProperties": false
            },
            "sync": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "applied"
                  ]
                },
                "generation": {
                  "type": "number"
                },
                "error": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "status",
                "generation",
                "error"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "app",
            "sync"
          ],
          "additionalProperties": false
        },
        "meta": {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            }
          },
          "required": [
            "requestId",
            "timestamp"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "ok",
        "data",
        "meta"
      ],
      "additionalProperties": false
    }
    Example response
    {
      "ok": true,
      "data": {
        "app": {
          "appId": "string",
          "instanceId": "string",
          "name": "string",
          "enabled": true,
          "source": "user",
          "settings": {
            "allowedOrigins": [
              "string"
            ],
            "clientEvents": true,
            "subscriptionCountEvents": true,
            "requireUserAuthentication": true,
            "maxConnections": 0,
            "maxChannelsPerConnection": 0,
            "maxPresenceMembers": 0,
            "maxMessageBytes": 0,
            "maxPublishesPerSecond": 0,
            "maxClientEventsPerSecond": 0,
            "history": {
              "mode": "off",
              "ttlSeconds": 0,
              "maxMessages": 0
            },
            "sessions": {
              "detachTtlSeconds": 0
            },
            "offlineQueue": {
              "enabled": true,
              "ttlSeconds": 0,
              "maxMessages": 0
            },
            "encryption": "off",
            "inspectorPayloadPreview": true
          },
          "settingsRevision": 0,
          "keys": [
            {
              "id": "string",
              "appId": "string",
              "key": "string",
              "secretHint": "string",
              "secretFingerprint": "string",
              "status": "active",
              "expiresAt": "string",
              "revokedAt": "string",
              "lastRevealedAt": "string",
              "createdAt": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        },
        "sync": {
          "status": "pending",
          "generation": 0,
          "error": "string"
        }
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top