Realm

Creating, retrieving and managing realms and also enabling, disabling and checking per realm security status.

Realms are routing and administrative domains that act as namespaces. All resources in Bondy belong to a Realm. Messages are routed separately for each individual realm so sessions attached to a realm won’t see message routed on another realm.

Types

realm

The representation of the realm returned by the read or write operations e.g. get, list, create or update.

uristringREQUIREDIMMUTABLE

The realm identifier

descriptionstringREQUIRED

A textual description of the realm.

is_prototypebooleanREQUIRED

If true this realm is a realm used as a prototype. Prototype realms cannot be used by themselves. Once a realm has been designated as a prototype it cannot be changed.

Default: false

prototype_uriuriIMMUTABLE

If present, this it the URI of the the realm prototype this realm inherits some of its behaviour and features from. This is an irreflexive property i.e. a realm cannot have itself as prototype.

is_sso_realmbooleanREQUIRED

If true this realm is an SSO Realm. Once a realm has been designated as an SSO realm it cannot be changed.

Default: false

sso_realm_uriuri

If present, this is the URI of the SSO Realm this realm is connected to. An update can change it only while the realm holds no users linked to its current SSO realm. When the realm is a prototype, the same check applies to each realm that inherits this property from it.

Default: The realm's prototype value if the realm inherits from a prototype (see prototype_uri), otherwise undefined.

allow_connectionsbooleanREQUIRED

If true this realm will allow connections from clients. It is normally set to false when the realm is an SSO Realm.

INFO

Prototype realms never allow connections, so if you set is_prototype to true this property will be assumed to be false.

Default: undefined

authmethodsarray[string]REQUIRED

The authentication methods set on this realm. The key is absent when the realm sets none and inherits them.

Default: The realm's prototype value if the realm inherits from a prototype, otherwise ["anonymous", "password", "oauth2", "wampcra", "ticket"].

rate_limitobject

The realm's own rate-limit budgets — the realm scope of the rate-limiting chain (see the rate limiting guide). A request is admitted only when the node, listener AND realm budgets all admit it, so these can only narrow what the node allows. Covers the classes a realm-addressed request reaches: auth, http and message. Setting the property to null on update clears it. :::warning Budgets are enforced per node: a total of N tokens per second bounds each cluster node separately. :::

authobject

Budgets for authentication attempts on this realm.

enabledboolean

Set to false to park this class's budgets without deleting the numbers. The block's presence enables it.

Default: true

per_callerobject

A budget per caller — per source IP, or per session for the message class.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

totalobject

One budget shared by ALL of the realm's callers — the tenant quota. Enforced per node.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

httpobject

Budgets for HTTP requests addressing this realm (API Gateway, MCP).

enabledboolean

Set to false to park this class's budgets without deleting the numbers. The block's presence enables it.

Default: true

per_callerobject

A budget per caller — per source IP, or per session for the message class.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

totalobject

One budget shared by ALL of the realm's callers — the tenant quota. Enforced per node.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

messageobject

Budgets for WAMP CALL/PUBLISH/SUBSCRIBE/REGISTER messages on this realm's sessions.

enabledboolean

Set to false to park this class's budgets without deleting the numbers. The block's presence enables it.

Default: true

per_callerobject

A budget per caller — per source IP, or per session for the message class.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

totalobject

One budget shared by ALL of the realm's callers — the tenant quota. Enforced per node.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

password_optsmapIMMUTABLE

The password hashing options of the realm. The key is absent when the realm sets none.

public_keysarray[map]IMMUTABLE

The public keys of the realm's signing keys, each as a JSON Web Key (JWK) map.

security_statusstring

The string 'enabled' if security is enabled on the realm. Otherwise the string is 'disabled'.

input_data

The object used to create or update a realm. Notice this object contains more information than the actually created realm e.g. users, groups, etc.

uristringREQUIREDIMMUTABLE

The realm identifier

descriptionstringREQUIRED

A textual description of the realm.

is_prototypebooleanREQUIRED

If true this realm is a realm used as a prototype. Prototype realms cannot be used by themselves. Once a realm has been designated as a prototype it cannot be changed.

Default: false

prototype_uriuriIMMUTABLE

If present, this it the URI of the the realm prototype this realm inherits some of its behaviour and features from. This is an irreflexive property i.e. a realm cannot have itself as prototype.

is_sso_realmbooleanREQUIRED

If true this realm is an SSO Realm. Once a realm has been designated as an SSO realm it cannot be changed.

Default: false

sso_realm_uriuri

If present, this is the URI of the SSO Realm this realm is connected to. An update can change it only while the realm holds no users linked to its current SSO realm. When the realm is a prototype, the same check applies to each realm that inherits this property from it.

Default: The realm's prototype value if the realm inherits from a prototype (see prototype_uri), otherwise undefined.

allow_connectionsbooleanREQUIRED

If true this realm will allow connections from clients. It is normally set to false when the realm is an SSO Realm.

INFO

Prototype realms never allow connections, so if you set is_prototype to true this property will be assumed to be false.

Default: undefined

authmethodsarray[string]REQUIRED

The list of the authentication methods allowed by this realm. Allowed values: 'anonymous', 'cookie', 'cryptosign', 'oauth2', 'oidcrp', 'password', 'ticket', 'tls', 'trust', 'wamp-scram', 'wampcra'. Bondy never offers 'tls' or 'oidcrp' to a WAMP session; see Authentication Method.

Default: The realm's prototype value if the realm inherits from a prototype, otherwise ["anonymous", "password", "oauth2", "wampcra", "ticket"].

security_enabledboolean

Whether security is enabled or not.

Default: undefined

rate_limitobject

The realm's own rate-limit budgets — the realm scope of the rate-limiting chain (see the rate limiting guide). A request is admitted only when the node, listener AND realm budgets all admit it, so these can only narrow what the node allows. Covers the classes a realm-addressed request reaches: auth, http and message. Setting the property to null on update clears it. :::warning Budgets are enforced per node: a total of N tokens per second bounds each cluster node separately. :::

authobject

Budgets for authentication attempts on this realm.

enabledboolean

Set to false to park this class's budgets without deleting the numbers. The block's presence enables it.

Default: true

per_callerobject

A budget per caller — per source IP, or per session for the message class.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

totalobject

One budget shared by ALL of the realm's callers — the tenant quota. Enforced per node.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

httpobject

Budgets for HTTP requests addressing this realm (API Gateway, MCP).

enabledboolean

Set to false to park this class's budgets without deleting the numbers. The block's presence enables it.

Default: true

per_callerobject

A budget per caller — per source IP, or per session for the message class.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

totalobject

One budget shared by ALL of the realm's callers — the tenant quota. Enforced per node.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

messageobject

Budgets for WAMP CALL/PUBLISH/SUBSCRIBE/REGISTER messages on this realm's sessions.

enabledboolean

Set to false to park this class's budgets without deleting the numbers. The block's presence enables it.

Default: true

per_callerobject

A budget per caller — per source IP, or per session for the message class.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

totalobject

One budget shared by ALL of the realm's callers — the tenant quota. Enforced per node.

rateintegerREQUIRED

Tokens per second — the sustained allowance, as a positive integer.

capacityintegerREQUIRED

The burst size — tokens a caller can spend at once before being held to the rate, as a positive integer.

usersarray[User]

A list of user objects.

groupsarray[object]

A list of group objects.

namestringREQUIREDIMMUTABLE

The group identifier.

groupsarray[string]

A list of group names.

metamapREQUIRED

Group metadata.

Default: {}

sourcesarray[source]

A list of source objects.

grantsarray[object]

A list of grant objects.

permissionsarray[string]REQUIRED

A list of permissions. Each permission is a URI. The WAMP permissions are 'wamp.register', 'wamp.unregister', 'wamp.subscribe', 'wamp.unsubscribe', 'wamp.call', 'wamp.cancel' and 'wamp.publish'. Bondy also checks 'bondy.issue' before it issues a ticket.

rolesarray[string]REQUIRED

A list of group names.

uristringREQUIRED

The URI or URI pattern the permissions apply to, matched according to match.

matchstringREQUIRED

Allowed values: 'exact', 'prefix', 'wildcard'

resourcesarray[object]

uristringREQUIRED

The URI or URI pattern this resource entry covers, matched according to its own match.

matchstringREQUIRED

Allowed values: 'exact', 'prefix', 'wildcard'

metamap

Grant metadata.

private_keysarray[private_key]

A list of private keys used for signing.

encryption_keysarray[private_key]

A list of private keys used for encryption.

API

Realm management is available over HTTP through the Admin HTTP API. Each route calls the matching Realm WAMP API procedure, which documents the arguments, results and errors.

Method	Path	WAMP procedure
GET	/realms	bondy.realm.list
POST	/realms	bondy.realm.create
GET	/realms/:realm_uri	bondy.realm.get
PUT	/realms/:realm_uri	bondy.realm.update
DELETE	/realms/:realm_uri	bondy.realm.delete
GET	/realms/:realm_uri/security_enabled	bondy.realm.security.is_enabled
PUT	/realms/:realm_uri/security_enabled	bondy.realm.security.enable
DELETE	/realms/:realm_uri/security_enabled	bondy.realm.security.disable