document auth details in #6731

1 files changed, 11 insertions, 1 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 0dbf7b0d..7d7a784e 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -865,7 +865,10 @@ Setting up instances
 
 .. http:patch:: /private/instances/$INSTANCE
 
-  Update the configuration of a merchant instance.
+  Update the configuration of a merchant instance.  PATCH operations against
+  an instance are authenticated by checking that an authorization is provided
+  that matches either the credential required by the instance being modified
+  OR the 'default' instance.
 
   **Request**
 
@@ -1058,6 +1061,10 @@ Deleting instances
   while disabling (the default) only deletes the private key
   and makes the instance unusable for new orders or payments.
 
+  For deletion, the authentication credentials must match
+  the instance that is being deleted or the 'default'
+  instance.
+
   **Request:**
 
   :query purge: *Optional*. If set to YES, the instance will be fully
@@ -1067,6 +1074,9 @@ Deleting instances
 
   :http:statuscode:`204 No content`:
     The backend has successfully removed the instance.  The body is empty.
+  :http:statuscode:`401 Unauthorized`:
+    The request is unauthorized. Note that for already deleted instances,
+    the request must be authorized using the 'default' instance.
   :http:statuscode:`404 Not found`:
     The instance is unknown to the backend.
   :http:statuscode:`409 Conflict`: