From 0410949c9a7bb3ea0c23ed1e06da2ea747437082 Mon Sep 17 00:00:00 2001 From: kojimaru Date: Fri, 5 Jun 2026 14:27:58 +0900 Subject: [PATCH 1/3] clarify Managed ToS scope for headless users and server auth --- .../permissions-and-errors/common-errors.md | 2 +- .../guides/security/terms-of-service/flow.md | 37 +++++++++++++++++++ .../guides/security/terms-of-service/index.md | 21 ++++++++++- .../security/terms-of-service/permissions.md | 11 +++++- 4 files changed, 68 insertions(+), 3 deletions(-) diff --git a/content/guides/api-calls/permissions-and-errors/common-errors.md b/content/guides/api-calls/permissions-and-errors/common-errors.md index 5b8da43ce..042275f38 100644 --- a/content/guides/api-calls/permissions-and-errors/common-errors.md +++ b/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 Terms of Service application flow. 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 | diff --git a/content/guides/security/terms-of-service/flow.md b/content/guides/security/terms-of-service/flow.md index 4142af7d6..d00202237 100644 --- a/content/guides/security/terms-of-service/flow.md +++ b/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 ToS 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 ToS is accepted | +| OAuth authorization code flow for a managed user | **Yes** — authorization is blocked until ToS 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 ToS + 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 diff --git a/content/guides/security/terms-of-service/index.md b/content/guides/security/terms-of-service/index.md index f43f309ff..ca2954152 100644 --- a/content/guides/security/terms-of-service/index.md +++ b/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 ToS 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 diff --git a/content/guides/security/terms-of-service/permissions.md b/content/guides/security/terms-of-service/permissions.md index 4edf848a5..74f153d58 100644 --- a/content/guides/security/terms-of-service/permissions.md +++ b/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 From 2236f44e55f67179b22354392f59213b556e3f09 Mon Sep 17 00:00:00 2001 From: kojimaru Date: Fri, 5 Jun 2026 14:32:42 +0900 Subject: [PATCH 2/3] fix: spell out Terms of Service to pass spelling lint --- content/guides/security/terms-of-service/flow.md | 10 +++++----- content/guides/security/terms-of-service/index.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/guides/security/terms-of-service/flow.md b/content/guides/security/terms-of-service/flow.md index d00202237..1690924c4 100644 --- a/content/guides/security/terms-of-service/flow.md +++ b/content/guides/security/terms-of-service/flow.md @@ -66,12 +66,12 @@ 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 ToS not accepted? | +| 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 ToS is accepted | -| OAuth authorization code flow for a managed user | **Yes** — authorization is blocked until ToS is 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 @@ -83,8 +83,8 @@ 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 ToS - acceptance is outstanding: +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 diff --git a/content/guides/security/terms-of-service/index.md b/content/guides/security/terms-of-service/index.md index ca2954152..6bc6a7ab8 100644 --- a/content/guides/security/terms-of-service/index.md +++ b/content/guides/security/terms-of-service/index.md @@ -31,7 +31,7 @@ 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 ToS required? | +| 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** | From 019dd3ca3940336444c9d21238686ce10f4654fa Mon Sep 17 00:00:00 2001 From: kojimaru Date: Fri, 5 Jun 2026 14:34:19 +0900 Subject: [PATCH 3/3] fix: add missing user-types reference link in ToS index --- content/guides/security/terms-of-service/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/guides/security/terms-of-service/index.md b/content/guides/security/terms-of-service/index.md index 6bc6a7ab8..29c986cee 100644 --- a/content/guides/security/terms-of-service/index.md +++ b/content/guides/security/terms-of-service/index.md @@ -82,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