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_addvec.adoc b/doc/man3/flux_msg_handler_addvec.adoc
index c1cd64dbfa55..d98837200885 100644
--- a/doc/man3/flux_msg_handler_addvec.adoc
+++ b/doc/man3/flux_msg_handler_addvec.adoc
@@ -49,6 +49,17 @@ handler, all previously created message handlers in the array are destroyed
 before an error is returned.
 
 
+SECURITY
+--------
+
+The _rolemask_ member of _struct flux_msg_handler_spec_ is passed
+to `flux_msg_handler_allow_rolemask()`.  If no additional roles besides the
+instance owner are to be allowed, set _rolemask_ to zero.
+
+See the SECURITY section of `flux_msg_handler_create(3)` for a description
+of message handler security.
+
+
 RETURN VALUE
 ------------
 
diff --git a/doc/man3/flux_msg_handler_create.adoc b/doc/man3/flux_msg_handler_create.adoc
index 23d4bf43fbe5..934f944ca718 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 *mh);
 
+ 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,43 @@ 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,
+or the message rolemask contains the FLUX_ROLE_OWNER (instance owner) role.
+
+By default, the message handler rolemask is 0, but roles may be added
+to the existing message handler rolemask with
+`flux_msg_handler_allow_rolemask()` or removed from it with
+`flux_msg_handler_deny_rolemask()`.  The FLUX_ROLE_OWNER bit position
+is ignored in the message handler rolemask.
+
+The following roles are defined in RFC 12:
+
+FLUX_ROLE_OWNER::
+The instance owner role has maximum privilege within the Flux instance.
+
+FLUX_ROLE_USER::
+The user role confers access, but not administrative privilege.
+
+In addition, RFC 12 defines these symbolic rolemask values:
+
+FLUX_ROLE_NONE::
+The empty set.
+
+FLUX_ROLE_ALL::
+The set of all possible roles.
+
+Other roles are yet to be defined.
+
+
 CAVEATS
 -------
 
@@ -103,3 +148,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]