Skip to content

Box Extract authentication guide


This is a step-by-step guide to creating an OAuth entry, acquiring credentials, and authorizing the Box Extract component for use in Matillion ETL.


  • The Box Extract component uses OAuth for third-party authentication.
  • While connector properties may differ between cloud data warehouses, the authentication process remains the same.

Creating an OAuth Entry in Matillion ETL

1. In Matillion ETL, click ProjectManage OAuth to open Manage OAuth.


If a Box Extract component has already been added to an orchestration job, the Manage OAuth dialog may also be accessed using the following method:

  1. Click the connector icon to open the Properties panel at the bottom of the screen.
  2. Click ... next to the Authentication property, and then click Manage.

2. Copy the Callback URL from the top of the Manage OAuth dialog. You need this for Acquiring Third-Party Credentials.


To authenticate with Box, the Callback URL must be a HTTPS URL.

3. Click in the bottom-left of the dialog to open the Add OAuth Entry dialog.

New OAuth entry

4. Provide a name for the OAuth in the Name field. Then, select Box from the Service drop-down, and then click OK.

Create OAuth Entry dialog

5. On returning to the Manage OAuth dialog, confirm the new entry.


This entry's Status is currently Not Configured.

New entry listed in Manage OAuth dialog

Acquiring Third-Party Credentials

1. Navigate to the Box App portal and enter valid login credentials to continue. Then, on the Box dashboard, click Dev Console on the left sidebar.

Box Dashboard

2. On the My Apps page, create a new app by clicking either the Create New App block at the left or the Create New App button at the top right.

My Apps dashboard

3. On the Create New App page, click Custom App.

Create new app page

4. On the Custom App dialog, select User Authentication (OAuth 2.0). Next, enter a unique name for the app in the App Name field, and then click Create App.

Custom App dialog

5. On the app's Configuration page, scroll down to the OAuth 2.0 Credentials section and copy the credentials from the Client ID and Client Secret fields by clicking COPY in those fields. Save these credentials.

Copy client ID and secret


  • Make sure to copy the Client Secret immediately as it only appears once.
  • When copying the credentials, some browsers may add a space to the end of the string. This causes the credentials to fail.

6. Next, in the OAuth 2.0 Redirect URI section of the page, paste the Callback URL (copied earlier from the Manage OAuth window in Matillion ETL) into the Redirect URIs field, overwriting the sample URI given there.

Paste redirect URL

7. In the Application Scopes section of the page, select the actions you want your app to perform. Matillion ETL requires the following actions:

  • Read all files and folders stored in Box
  • Write all files and folders stored in Box

Select application scopes

8. Finally, click Save Changes at the top of the page.

Authorizing for Use in Matillion ETL

1. Return to the Manage OAuth window in Matillion ETL and click next to the previously created OAuth entry. This will open the Configure OAuth window.

2. Using the credentials copied from the Box app configuration earlier, provide details for the following fields:

Configure OAuth

3. The next window will have an Authorization link. Click the link to authorize Matillion ETL to use the acquired credentials.

4. The browser will redirect you to a Box dialog requesting access to the account associated with the app. Click Grant access to Box to confirm.

5. If all is successful, the browser will return to Matillion ETL with a window stating, "Authorization Successful".