How to connect Box using Medialake's provided OAuth app, enable it for your organisation when required, and understand exactly what access is granted.

What to expect

The preferred setup uses the Medialake-provided Box OAuth app. It is a Box Platform App using User Authentication (OAuth 2.0). Most customers do not need to create their own Box app or provide a Client Secret.

There are two possible parts to the setup:

If your Box enterprise restricts unpublished or custom applications, a Box administrator enables the Medialake app once for the enterprise.
A Box user signs in on Box's official authorization screen and grants the app access to the content that user can already access.

You approve the connection on Box, and you can revoke it at any time. Medialake never sees or stores your Box password. The sign-in happens on Box's site, after which Box returns an authorization code to your Medialake environment. Medialake exchanges that code for access and refresh tokens.

We follow the principle of least privilege. The Box connector only reads content: it identifies the connected user, browses folders and collections, reads file metadata, retrieves thumbnails, and downloads selected file content for syncing. It does not create, edit, rename, move, share, or delete anything in Box.

Box administrator          Medialake                     Box│  enable Medialake app, if required                ││───────────────────────────────────────────────────▶││                         │                          │Box user                     │                          ││  connect source       │                          ││──────────────────────▶│                          ││  redirect to Box      │                          ││◀──────────────────────│                          ││  sign in and grant access                       ││─────────────────────────────────────────────────▶││  redirect with authorization code               ││◀─────────────────────────────────────────────────││                       │  exchange code            ││                       │──────────────────────────▶││                       │  access + refresh tokens  ││                       │◀──────────────────────────││  choose content       │                          ││  to sync              │                          ││──────────────────────▶│                          │

Before you begin

You will need:

A Box account that can view and download the content you want to sync
Access to the Box integration settings in Medialake
A Box enterprise administrator if your organisation restricts unpublished or custom apps

The Medialake-provided Box app uses this Client ID:

mu4zp0sa6p8gct5pubkwrzwd4y30fi01

Recommended: use the Medialake-provided OAuth app

Medialake recommends this option for all customers. Use the Medialake-provided app unless your organisation specifically requires a customer-owned OAuth application. This is the simplest setup because Medialake maintains the OAuth configuration and credentials. You only need to enable the Client ID in Box if your enterprise security settings require administrator approval, then connect your Box account from Medialake.

The user connecting Box does not need access to the Box Developer Console and does not need a Client Secret.

Enable the OAuth app for your Box enterprise, if required

OAuth 2.0 user-authentication apps do not always need separate administrator approval. An enterprise administrator must enable the app when your Box enterprise settings block unpublished or custom applications.

When using the preferred Medialake-provided app, enter Client ID mu4zp0sa6p8gct5pubkwrzwd4y30fi01. If your organisation has chosen to create its own OAuth app, enter that app's Client ID instead.

If a user sees an app-disabled or administrator-approval message:

In the Box Admin Console, open Integrations.
Open Platform Apps Manager.
Select Add Platform App and enter the appropriate Client ID.
Open User Authentication Apps and select the Medialake app.
Set the app to an enabled or available state for the users or groups who need it.
Select Apply.

This is normally a one-time action for the Box enterprise. Individual users do not need to add the app themselves, but each user who connects Box must still sign in and grant Medialake access to the content available to their account. Other Box enterprises may need their own administrator to enable the app, depending on their security settings.

The exact labels can vary with your Box plan and admin-console version. See Box's Managing platform apps guide for the current controls.

Connect Box in Medialake

The connection is tied to the Box user who completes the OAuth flow. It should be connected by someone who:

Can view and download all files and folders that need to be synced.
Has access to any Box metadata that Medialake needs to read.
Is a permanent member of your team, or is a dedicated managed account with an established owner and recovery process.

To connect:

Add or connect the Box source in Medialake.
On Box's authorization screen, confirm that the app name is Medialake AI, or the name of your customer-owned app if you are using one.
Sign in with the intended Box account.
Review the requested read access and select Grant access to Box.
After Box returns you to Medialake, choose the folders or collections to sync.

Optional: use a customer-owned OAuth app

Only follow the steps below if your organisation requires ownership of the Box OAuth application and credentials.

Step 1: Create the Box Platform App

Sign in to the Box Developer Console.
Select Create Platform App.
Choose Platform App as the application type.
Give the app a recognisable name, such as Your Company — Medialake.
For the purpose, choose Integration and identify Medialake as the external system. Complete any additional ownership or category fields shown by Box.
Select User Authentication (OAuth 2.0).
Select Create App.

Box does not let you change the authentication method after the app is created. If a different method was selected, create a new Platform App.

Step 2: Configure the redirect URI

In the app's Configuration tab, add this value under OAuth 2.0 Redirect URIs:

https://oauth2.medialakeapp.com/box-redirect

Box performs an exact-match check. The scheme, domain, path, query string, and trailing slash must match the redirect URI used by Medialake. Use HTTPS for production environments.

Step 3: Grant only the required application scope

Under Application Scopes, select:

Box application scope	OAuth scope	How Medialake uses it
Read all files and folders stored in Box	`root_readonly`	Read the connected user's name and login, browse folders and collections, read file metadata, retrieve thumbnails, and download selected file content for syncing.

Leave Read and write all files and folders stored in Box and all management scopes unselected. Medialake does not require:

root_readwrite
User or group management
Enterprise property management
Webhook management
Retention, legal hold, or sign-request management
The advanced feature that lets an app perform actions as other users

Medialake makes Box API requests from its server, so no CORS domain is required.

Save the configuration before continuing.

>How Box permissions combine: the application scope and the connected user's own Box permissions are both enforced. root_readonly allows the app to read content, but it does not give the user access to files or folders they could not already access.

Step 4: Add the credentials to Medialake

In the Box app's Configuration tab, find OAuth 2.0 Credentials and securely copy:

Client ID
Client Secret

Open the Box integration settings in Medialake and enter the values in the corresponding fields. Save the settings.

Do not use a developer token. Box developer tokens expire after one hour and are intended only for testing in the Developer Console.

>Keep the Client Secret private. Store it in an approved password manager or secret-management system. Do not email it, paste it into a support ticket, or commit it to source control.

Limiting what Medialake can access

The OAuth token can read the Box content visible to the connected user. Selecting folders in Medialake controls what is actively synced, but it does not narrow the Box token itself to only those folders.

For the narrowest possible connection:

Use a dedicated managed Box user where practical.
Give that user access only to the folders required for the integration.
Use the lowest Box collaboration role that still permits viewing metadata and downloading content.
Remove access to out-of-scope folders before authorizing the connection.
Review the user's folder collaborations and the Platform App's scopes periodically.

Box continues to enforce file-level and folder-level restrictions. If the connected user cannot see or download an item in Box, Medialake cannot sync it.

What Medialake can and cannot do

With the configuration above, Medialake can:

Read the connected user's name, email address, and Box user ID
List folders, files, and the collections exposed by the Box API
Read names, extensions, sizes, timestamps, status, shared-link metadata, and applied metadata returned by Box
Retrieve thumbnails
Download selected file content into Medialake

Medialake cannot:

See or store the user's Box password
Access content the connected user cannot access
Bypass a Box download restriction
Upload, replace, rename, move, share, or delete Box files or folders
Create or change collaborations, comments, or tasks
Manage Box users, groups, enterprise settings, retention policies, or legal holds
Act as another Box user

Staying connected

Box access tokens are valid for approximately 60 minutes. Medialake renews them automatically using a rotating refresh token.

Each Box refresh token:

Can be used only once
Is valid for up to 60 days
Is replaced with a new refresh token when it is used, restarting the 60-day window

If the connection is not used or refreshed within 60 days, Box requires the user to authorize it again. Reauthorization may also be required if the user revokes access, loses access to the app, the enterprise disables the app, or the app's credentials are changed.

Revoking access

To revoke the OAuth grant from Box:

In Box, open Account menu → Integrations.
Open My Integrations.
Find the app created for Medialake and select Remove.

An enterprise administrator can also disable the app in Admin Console → Integrations → Platform Apps Manager.

Disconnect or delete the Box source in Medialake as well if it should no longer sync. Removing the app in Box invalidates its authorization; reconnecting later requires a new OAuth grant.

Troubleshooting

Symptom	What to check
`redirect_uri_mismatch` or `redirect_uri_missing`	Confirm that the HTTPS redirect URI in Box exactly matches the URI used by Medialake, including the path and trailing slash.
`invalid_client` or the connection fails before login	If you use the Medialake-provided app, contact Medialake Support with the error message. For a customer-owned app, re-enter the Client ID and Client Secret, confirm they came from the same Platform App, and check that the secret has not been rotated.
Box says the app is disabled or needs administrator action	Ask a Box enterprise administrator to enable the Client ID under Platform Apps Manager → User Authentication Apps.
The connection succeeds but a folder is missing	Confirm that the connected Box user can see the folder and that it was selected for syncing in Medialake.
Metadata appears but a file cannot be synced	Confirm that the connected user has download permission and that Box security controls do not block the download.
The connection becomes unauthorized after a long period without activity	Box refresh tokens expire after 60 days if they are not used. Reconnect the Box source in Medialake.
Box shows broader access than expected	Recheck the Platform App's Application Scopes. Only Read all files and folders stored in Box should be selected.

If the issue continues, contact [email protected] with the app name, Client ID, Medialake environment URL, and the error message. Do not include the Client Secret, access token, or refresh token.

Box — Authentication