document as_user_id

Change-Id: Iaaa2a87c2577333b3435bb548ba6bf13930a1fa9
Reviewed-on: https://gerrit.instructure.com/15757
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Brian Palmer <brianp@instructure.com>

doc/api/layout/html/sidebar.erb

@@ -5,6 +5,7 @@
   <a href="<%= url_for("file.pagination.html") %>" class="<%= 'current' if options[:object] == 'file.pagination.html' %>">Pagination</a>
   <a href="<%= url_for("file.file_uploads.html") %>" class="<%= 'current' if options[:object] == 'file.file_uploads.html' %>">File Uploads</a>
   <a href="<%= url_for("file.endpoint_attributes.html") %>" class="<%= 'current' if options[:object] == 'file.endpoint_attributes.html' %>">API Endpoint Attributes</a>
+  <a href="<%= url_for("file.masquerading.html") %>" class="<%= 'current' if options[:object] == 'file.masquerading.html' %>">Masquerading</a>
   <h2>Resources</h2>
   <a <%= "class='current'" if options[:all_resources] %> href="all_resources.html">All Resources Reference</a>
   <% options[:resources].each_with_index do |(resource, controllers), i| %>

doc/api/masquerading.md

@@ -0,0 +1,21 @@
+Masquerading
+============
+
+Masquerading is making an API call on behalf of another user. It will behave as if the target user had made the API
+call with his own access token (even if he doesn't have one), including permission checks, enrollments, etc. In order
+to masquerade via the API, the calling user must have the "Become other users" permission. If the target user is also
+an admin, the calling user must additionally have every permission that the target user has. For auditing purposes,
+all calls log both the calling user and the target user.
+
+To masquerade, add an as_user_id parameter to any request. It can be either a Canvas user ID, or an SIS user ID
+(as described in <a href="object_ids.html">SIS IDs</a>):
+
+    curl 'https://<canvas>/api/v1/users/self/activity_stream?as_user_id=sis_user_id:brian' \
+         -H "Authorization: Bearer <token>"
+
+Masquerading could be useful in a number of use cases:
+
+ * For developing an admin tool
+ * For accessing APIs that can only be called on self (i.e. the activity stream as shown above)
+ * For a portal type application that's already tightly integrated with an SIS and is managed
+   by the school, to avoid going through the OAuth flow for every student