DDOC-1723: Clarify Custom Terms of Service scope for headless users

content/guides/api-calls/permissions-and-errors/common-errors.md

@@ -183,7 +183,7 @@ for solution to common errors encountered when working with the Box APIs.
 |   |    |
 | **Error**    | `terms_of_service_required`   |
 | **Message**  | User must accept custom terms of service before action can be taken  |
-| **Solution** | The admin of your Box account has set custom terms of service and the user has not logged in to accept the terms yet. The user will need to accept the terms of service, or the admin will have to disable them, in order to proceed. More information is available [here](https://support.box.com/hc/en-us/articles/360044192733-Using-Custom-Terms-Of-Service). |
+| **Solution** | The user in context for the API request has not accepted the enterprise's custom Terms of Service. For login-capable managed users, acceptance is required before most API calls, user access token issuance, or OAuth authorization can proceed. Service accounts and App Users are exempt. If you are using server authentication with the `As-User` header or a user access token, the impersonated or token subject user must have accepted. The user can accept via the Box web application, or your application can accept programmatically using the <Link href="/guides/security/terms-of-service/flow">Terms of Service application flow</Link>. More information is available [here](https://support.box.com/hc/en-us/articles/360044192733-Using-Custom-Terms-Of-Service). |
 |  |   |
 | **Error**| `user_already_collaborator`  |
 | **Message**  | User is already a collaborator  |

content/guides/security/terms-of-service/flow.md

@@ -59,6 +59,43 @@ When the user accepts or rejects the terms, it makes a call to either
 [`POST /terms_of_service_user_statuses`][post_tosus] depending on if the initial
 error returned a `tos_user_status_id` in the response.
 
+## Server authentication and impersonation
+
+Applications using JWT, Client Credentials Grant (CCG), or OAuth 2.0 may act as
+a [service account][user-types], an [App User][user-types], or a managed user.
+Terms of Service enforcement depends on which user is in context for the API
+request.
+
+| Scenario | Blocked if Managed Terms of Service not accepted? |
+| -------- | ------------------------------------ |
+| API call with a service account or App User token (no `As-User`) | **No** — headless users are exempt |
+| API call with CCG/JWT and [`As-User`][as-user] set to a managed user | **Yes** — the impersonated user must have accepted |
+| User access token issued for a managed user | **Yes** — token issuance is blocked until Terms of Service is accepted |
+| OAuth authorization code flow for a managed user | **Yes** — authorization is blocked until Terms of Service is accepted |
+| API call with `As-User` set to a service account or App User | **No** — headless users are exempt |
+
+### Accepting Terms of Service programmatically
+
+When a managed user has not accepted Managed Terms of Service, most API calls
+made on their behalf return `terms_of_service_required`. To resolve this
+without requiring the user to sign in to the Box web application:
+
+1. Obtain a server authentication access token (JWT or CCG).
+2. Set the [`As-User`][as-user] header to the managed user's ID so subsequent
+   requests run in that user's context.
+3. Call the Terms of Service endpoints, which remain available even when Terms
+   of Service acceptance is outstanding:
+   * [`GET /terms_of_services/:id`][get_tos_id] to retrieve the terms text
+   * [`POST /terms_of_service_user_statuses`][post_tosus] or
+     [`PUT /terms_of_service_user_statuses/:id`][put_tosus] to accept or reject
+4. Retry the original API call.
+
+An admin cannot accept Managed Terms of Service for another user without using
+the `As-User` header to act as that user. Acceptance must be recorded for the
+user who is subject to the Terms of Service.
+
+[as-user]: g://authentication/oauth2/as-user
+[user-types]: page://platform/user-types
 [put_tosus]: e://put_terms_of_service_user_statuses_id
 [post_tosus]: e://post_terms_of_service_user_statuses
 [get_tos_id]: e://get_terms_of_services_id

content/guides/security/terms-of-service/index.md

@@ -18,10 +18,29 @@ within which all users are allowed to work with an enterprise's data in Box.
 
 There are currently two types of Terms of Service for any enterprise that can be
 enabled independently. The **Managed Terms of Service** can be
-enabled for the enterprise's own users, where the **External Terms of Service*
+enabled for the enterprise's own users, where the **External Terms of Service**
 can be enabled for users from other enterprises that collaborated in on the
 primary enterprise's data.
 
+### Who is subject to Managed Terms of Service?
+
+When Managed Terms of Service is enabled for an enterprise, it applies to
+**login-capable managed users** in that enterprise. These are users who can sign
+in to Box (for example, standard managed users with credentials).
+
+The following user types are **not** subject to Managed Terms of Service, even
+though they belong to the enterprise:
+
+| User type | Managed Terms of Service required? |
+| --------- | --------------------- |
+| Admin/Co-Admin and Managed user (can log in to Box) | **Yes** |
+| [Service account][user-types] (Automation User) | **No** |
+| [App User][user-types] | **No** |
+
+Service accounts and App Users are API-only, headless users. They are exempt
+from Managed Terms of Service enforcement. The Admin Console setting for
+managed users refers to these login-capable users, not every enterprise member.
+
 ## Terms of Service User Statuses
 
 A Terms of Service User Status represents the status of the Terms of Service
@@ -63,6 +82,7 @@ outlined actions.
 * **Manage Enterprise Properties**: Required to enable or edit the enterprise's settings for Terms of Services as well as to view them for external users.
 * **Manage Users**: Required to accept Terms of Services for other users.
 
+[user-types]: page://platform/user-types
 [euserstatuses]: e://get-terms-of-service-user-statuses
 [euserstatuses_put]: e://put-terms-of-service-user-statuses-id
 [euserstatuses_post]: e://post-terms-of-service-user-statuses

content/guides/security/terms-of-service/permissions.md

@@ -24,6 +24,11 @@ An end user is considered subject to Terms of Service when:
     * A managed Terms of Service for a user that is part of the same enterprise
     * An external Terms of Service for users collaborating into the enterprise
 
+For **Managed** Terms of Service specifically, the user must also be a
+login-capable managed user. [Service accounts][user-types] and
+[App Users][user-types] are headless users and are not subject to Managed Terms
+of Service, even when they belong to the enterprise.
+
 Terms of Service settings can be viewed by an end user if:
 
 * The user is subject to a  Terms of Service; and
@@ -38,7 +43,7 @@ if:
 
 Terms of Service settings can be edited by an enterprise admin or co-admin if:
 
-* They have **'Edit settings for your company** permissions
+* They have **Edit settings for your company** permissions
 * The application has the **Manage enterprise properties** scope enabled
 * The Terms of Service belongs to their enterprise
 
@@ -67,6 +72,7 @@ enterprise admins and co-admins if:
 
 * They have **Manager users** permissions
 * The application has the **Manage users** scope enabled
+* The application has the **As-User**[as-user] scope enabled
 * The end user is subject to the Terms of Service
 * The end user is not an admin or co-admin
 * The Terms of Service belongs to their enterprise
@@ -76,3 +82,6 @@ An end user cannot accept, reject, view external Terms of Service settings for
 an enterprise they are collaborating into until the end user accepts the managed
 Terms of service for their own enterprise, where applicable. Trying to do so
 will result in a `TERMS_OF_SERVICE_REQUIRED` error.
+
+[user-types]: page://platform/user-types
+[as-user]: g://authentication/oauth2/as-user