data/api/client-server/definitions/security.yaml

@@ -18,10 +18,14 @@ accessTokenBearer:
     or [login](/client-server-api/#login), using the `Authorization: Bearer` header.
 
     It can also be the `as_token` of an application service.
+
+    This is the preferred method.
   scheme: bearer
 appserviceAccessTokenBearer:
   type: http
   description: |-
     The `as_token` of an application service, using the `Authorization: Bearer`
     header.
+
+    This is the preferred method.
   scheme: bearer

data/api/identity/definitions/security.yaml

@@ -16,4 +16,6 @@ accessTokenBearer:
   description: |-
     The `access_token` returned by a call to `/register`, using the
     `Authorization: Bearer` header.
+    
+    This is the preferred method.
   scheme: bearer