Prepare a Box identifier
01In brief #sec_d80f63df
REVIEWIT collects a Box company through a Box application you create in the Box developer console, in Server Authentication mode (Client Credentials Grant). You provide REVIEWIT with three values: the Enterprise ID, the Client ID, and the Client Secret of this application. REVIEWIT then obtains the service account token for the application, valid for one hour, and only reads.
Box does not offer a "read-only" scope for administration: the Manage users or Manage groups scopes also allow writing, and the as-user option allows acting on behalf of a user. REVIEWIT uses it only for reading: each call it is authorized to make is written in the resource contract, and nothing else is sent.
021. Create the application #sec_02ac4128
In the Box Developer Console (app.box.com/developers/console), with an account from your company:
- Create Platform App › Custom App;
- authentication method Server Authentication (Client Credentials Grant);
- name it, for example REVIEWIT Collector.
To see the Client Secret, two-factor authentication must be activated on the developer account.
032. Configure the application #sec_9b48a95f
Configuration tab:
- App Access Level: App + Enterprise Access. Without it, the application cannot see any user in the company, and REVIEWIT refuses the connection.
- Application Scopes, to check according to the resources you want to collect:
| Scope | What it opens to REVIEWIT |
|---|---|
| Read all files and folders stored in Box | Shared folders, collaborations, shared links, hubs |
| Manage users | Managed users, administrators, external collaborators, application users |
| Manage groups | Groups, members, group administrators |
| Manage enterprise properties | Administration log (last login), allowed domains, information barriers, Slack and Teams connections, enterprise hubs |
| Manage retention policies | Retention policies (Box Governance) |
| Manage legal holds | Legal holds (Box Governance; scope on demand from Box support) |
- Advanced Features: check Make API calls using the as-user header. The service account only sees its own folder: your users' content is read on their behalf, read-only.
A scope you do not check does not block the connection: resources that depend on it simply remain uncollectable, and the Prepare step of the assistant names them. A module you have not subscribed to (Box Governance, Box Shield) is read as "not subscribed", never "empty".
043. Have the application authorized by an administrator #sec_209c1692
A Client Credentials Grant application only works when authorized in your company:
- application Authorization tab › Review and Submit;
- a Box administrator: Admin Console › Platform › Platform Apps, the submitted application › Authorize (or Add with its Client ID).
Any change to scopes or access requires a new authorization (Platform Apps › … › Reauthorize): until it is done, Box applies the old configuration.
054. Retrieve the three values #sec_6b0a65ee
| Value | Where to find it |
|---|---|
| Enterprise ID | Admin Console › Account & Billing › Account Information (a number); also in the General Settings tab of the application |
| Client ID | Application › Configuration › OAuth 2.0 Credentials |
| Client Secret | Same place (Fetch Client Secret) |
In REVIEWIT: Connections › New connection › Box, enter the three values. The verification:
- obtains the service account token;
- verifies that this account belongs to the entered enterprise;
- verifies that it sees the enterprise users (App + Enterprise Access).
Then the rights proof checks each scope with minimal reading: Box does not allow an application to list its own scopes.
065. If the connection is denied #sec_28cc585b
| Box Message | Cause | Action |
|---|---|---|
| unauthorized_client | The application is not authorized in the enterprise | Section 3 |
| invalid_grant / invalid_client | Wrong or regenerated secret, or Enterprise ID that is not the one used for authorization | Copy the secret again, verify the Enterprise ID |
| The grant type is unauthorized | The application is not set to Client Credentials Grant | Create a Server Authentication application (Client Credentials Grant) |
| the app reaches the enterprise but cannot list its users | App Access Only, or Manage users scope missing | Section 2, then reauthorize (section 3) |
| insufficient_scope | A scope is missing | Check the scope, then reauthorize |
The secret only changes if you regenerate it: do this whenever someone who has seen it leaves, then replace it in REVIEWIT.