diff --git a/doc/man3/Makefile.am b/doc/man3/Makefile.am
index cfa1e9a61f42..7d6819098568 100644
--- a/doc/man3/Makefile.am
+++ b/doc/man3/Makefile.am
@@ -88,6 +88,8 @@ MAN3_FILES_SECONDARY = \
 	flux_msg_handler_destroy.3 \
 	flux_msg_handler_start.3 \
 	flux_msg_handler_stop.3 \
+	flux_msg_handler_allow_rolemask.3 \
+	flux_msg_handler_deny_rolemask.3 \
 	flux_msg_handler_delvec.3 \
 	flux_child_watcher_get_rpid.3 \
 	flux_child_watcher_get_rstatus.3 \
@@ -202,6 +204,8 @@ flux_check_watcher_create.3: flux_idle_watcher_create.3
 flux_msg_handler_destroy.3: flux_msg_handler_create.3
 flux_msg_handler_start.3: flux_msg_handler_create.3
 flux_msg_handler_stop.3: flux_msg_handler_create.3
+flux_msg_handler_allow_rolemask.3: flux_msg_handler_create.3
+flux_msg_handler_deny_rolemask.3: flux_msg_handler_create.3
 flux_msg_handler_delvec.3: flux_msg_handler_addvec.3
 flux_child_watcher_get_rpid.3: flux_child_watcher_create.3
 flux_child_watcher_get_rstatus.3: flux_child_watcher_create.3
diff --git a/doc/man3/flux_msg_handler_create.adoc b/doc/man3/flux_msg_handler_create.adoc
index 4b0c9c15b7a8..2d53ce87f208 100644
--- a/doc/man3/flux_msg_handler_create.adoc
+++ b/doc/man3/flux_msg_handler_create.adoc
@@ -6,7 +6,9 @@ flux_msg_handler_create(3)
 NAME
 ----
 flux_msg_handler_create, flux_msg_handler_destroy,
-flux_msg_handler_start, flux_msg_handler_stop -  manage message handlers
+flux_msg_handler_start, flux_msg_handler_stop,
+flux_msg_handler_allow_rolemask,
+flux_msg_handler_deny_rolemask  -  manage message handlers
 
 
 SYNOPSIS
@@ -30,6 +32,12 @@ SYNOPSIS
 
  void flux_msg_handler_stop (flux_msg_handler_t *w);
 
+ void flux_msg_handler_allow_rolemask (flux_msg_handler_t *w,
+                                       uint32_t rolemask);
+
+ void flux_msg_handler_deny_rolemask (flux_msg_handler_t *w,
+                                      uint32_t rolemask);
+
 
 DESCRIPTION
 -----------
@@ -59,6 +67,23 @@ are automatically sent an ENOSYS response by the dispatcher.
 stopping it.
 
 
+SECURITY
+--------
+
+As described in RFC 12, Flux connectors authenticate each broker
+connection, mapping it to a Flux userid and set of "roles" allocated
+to that user.  This userid and rolemask is stamped on all messages
+originating from the connection.
+
+A message handler only receives a message if a bit-wise AND of the message
+rolemask and the message handler rolemask evaluates to a non-zero value.
+By default, the message handler rolemask contains only FLUX_ROLE_OWNER
+(the instance owner) but may be changed with
+`flux_msg_handler_allow_rolemask()` and `flux_msg_handler_deny_rolemask()`,
+which add or remove roles from the message handler rolemask.  FLUX_ROLE_OWNER
+cannot be dropped from the message handler rolemask.
+
+
 CAVEATS
 -------
 
@@ -103,3 +128,5 @@ include::COPYRIGHT.adoc[]
 SEE ALSO
 ---------
 flux_get_reactor(3), flux_reactor_start(3), flux_msg_cmp(3)
+
+https://github.com/flux-framework/rfc/blob/master/spec_6.adoc[RFC 12: Flux Security Architecture]