Doc tweaks on trusted stuff

authentication.rst

@@ -18,10 +18,16 @@ the identity of your client *and* prove that the user has given your
 client permission to act on their behalf. We'll talk about each type
 of auth in detail below.
 
-Most API methods in place require User authentication. Client authentication
-is sufficient only in the case your client is marked as a `trusted` client.
-If you've contacted us and we've labeled you as a trusted client you will
-find extra notes sprinkled throughout the documentation.
+.. _trusted-clients:
+
+Most of the API methods currently in place require user auth. For
+example, to create a new list you'll need the authorization of the
+person you are creating the list on behalf of. In some cases, clients
+need to create or update lists on behalf of themselves, without
+requiring user auth. This is supported, but you'll need to ask us for
+special permission to create these "ownerless" lists. Throughout this
+documentation you'll see notes about `trusted` clients. Those notes
+are for clients who have been granted this special permission.
 
 OAuth
 -----
@@ -253,11 +259,11 @@ to use instead.
 Refresh Token
 -------------
 
-User access tokens tend to expire within a few hours of them being granted. If
-your application needs to take action on behalf of a user that is offline, a
-refresh token is the solution. When a client is granted a user access token
-the response also contains a ``refresh_token``. A refresh token can be
-exchanged for a fresh user access token in addition to a new refresh token.
+User access tokens expire within a few hours of being granted. If your
+application needs to take action on behalf of a user that is offline,
+you can use a **refresh token**. When you are granted a user access
+token the response also contains a ``refresh_token``. The refresh
+token can be exchanged for a fresh user access token at any time.
 
 .. code-block:: console
 
@@ -269,11 +275,11 @@ exchanged for a fresh user access token in addition to a new refresh token.
 
 
 .. note:: For security reasons refresh tokens must be discarded after
-   being used. A new refresh token is supplied and must be used the next
-   time you want a fresh user access token.
+   being used. A new refresh token is included in the response and
+   must be used the next time you want a fresh user access token.
 
-Refresh tokens can be exchanged indefinitely until a user revokes access
-to your application.
+Refresh tokens can be exchanged indefinitely, unless a user revokes
+access for your application.
 
 Revoked Tokens
 --------------

list-management-api.rst

@@ -134,15 +134,17 @@ group. We'll start with :http:post:`/group`:
     `description` and `domain` are as described above for the method's
     input.
 
+.. note:: If your client is :ref:`trusted <trusted-clients>`, you can
+   create a group with :ref:`client <client-auth>` instead
+   of :ref:`user <user-auth>` auth. In that case, you should not include
+   the `creator` field; the only available parameters are `domain` and
+   a `description`. If a creator is supplied, a user access token is
+   required.
+
 After creating the group, our list will have a single membership: the
 group's creator. Let's add another member using the `members` URI that
 was returned above:
 
-    .. note:: Trusted clients may create a group without user access. To do
-              this the client must not supply a creator. The only available
-              paramters are a domain and a group description. If a creator
-              is supplied, a user access token is expected.
-
 .. http:post:: /membership/(string: group_id)
 
     Add a group membership. Requires :ref:`user-auth` with "modify"
@@ -224,9 +226,10 @@ was returned above:
 
     `group_name` is the name of the group as used by this user.
 
-    .. note:: Trusted clients do not need :ref:`user-auth` for this API
-              call. A trusted client only needs to have created the group
-              to be able to add members to the group.
+.. note:: If your client is :ref:`trusted <trusted-clients>`, you can
+   use :ref:`client <client-auth>` instead of :ref:`user <user-auth>`
+   auth for this call, as long as your client was the original creator
+   of the group.
 
 .. _message: