why deepstreamHub? compare us getting started feature roadmap faq
use cases pricing
enterprise blog contact

Security in deepstreamHub is based on three interrelated concepts:

  • encrypted connections
  • user authentication
  • granular permissions

Here's how they work together:

Encrypted Connections

deepstreamHub supports transport layer security for web-facing connections Secure Web Sockets. WSS is the default protocol and will be part of your app-url.


Every incoming connection needs to pass an authentication step. This happens when the client calls login( data, callback ). deepstreamHub offers a variety of ways to handle incoming authentication data:

  • Open Authentication allows every connection. Choose this option for public sites that don't require access controls.
  • Email Auth uses deepstreamHub's built-in user management capabilities. Users can be registered manualy via the dashboard or programmatically via the http api
  • HTTP Webhook contacts a configurable HTTP webhook to ask if a user is allowed to connect. This is the most flexible option as it allows you to write a tiny http server in any language that can connect to databases, active directories, oAuth providers or whatever else your heart desires.

Apart from just accepting / denying incoming connections, the authentication step can also provide two extra bits of information:

  • clientData is returned to the client upon login. This is useful to provide user specific settings, e.g. { "view": "author" } for a blog CMS.
  • serverData is kept privately on the server and can be used within Valve permissions whenever a client attempts an action. This makes certain security concepts possible, e.g. role based authentication.
"system-settings": {
    //publicly readable
    "read": true,
    //writable only by admin
    "write": "user.data.role === 'admin'"

Authentication FAQ

  • When exactly does authentication happen? When a deepstream client is created it establishes a connection straight away. The connection however remains in a quarantine state until login() is called. This makes sure that auth-data is sent over an encrypted connection and helps to get the at times time-consuming connection establishment out of the way while the user is busy typing passwords.
  • Can I read usernames for auth purposes out of a deepstream record? There's no built-in support for this, but it's easy to read data from deepstreamHub from within an HTTP Webhook.
  • Can a user connect more than once at the same time? Yes. The same user can connect multiple times from separate browser windows or devices.


Permissioning is the act of deciding whether a specific action, e.g. writing to a record or subscribing to an event is allowed. To help with this, deepstream uses an expressive, rule-based permissioning language called Valve. There's a lot to say about Valve. Here's a small Valve File that should give you a first impression, to learn more though head over to the simple valve tutorial


    create: true
    delete: true
    write: true
    read: true
    listen: true

    read: true
    create: "user.id === $userid"
    write: "user.id === $userid"

    write: "!oldData.value || data.value > oldData.value"
    create: true
    read: true

    delete: "$firstname.toLowerCase() === 'egon' && $lastname.toLowerCase() === 'miller'"

    create: true
    write: "_('item/' + data.itemId ).stock > 0"


    listen: true
    publish: true
    subscribe: true

    listen: true
    publish: true
    subscribe: true

    publish: false
    subscribe: false

    publish: "user.id === 'client-a'"
    subscribe: "user.id === 'client-b'"

    publish: "$topic === 'tea-cup-pigs'"

    publish: "typeof data === 'number' && data > 10"

    publish: "$city.toLowerCase() === data.address.city.toLowerCase()"


    provide: true
    request: true

    provide: "user.id === 'client-a'"
    request: "user.id === 'client-b'"

    request: "typeof data.firstname === 'string' && typeof data.lastname === 'string'"