> For the complete documentation index, see [llms.txt](https://docs.onum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onum.com/the-workspace/listeners/listener-integrations/pull-data-from-http-endpoints/collect-data-from-box.md). # Collect data from Box ## Overview Use the **HTTP Pull** Listener to collect data from the [Box API](https://developer.box.com/reference/get-events). Currently, we support the events endpoint. ## HTTP Pull Listener configuration In Falcon Onum, go to the **Listeners** area and click **New Listener > HTTP Pull**. Give a name to your new Listener and enter the following data: ### Parameters N/A ### Secrets You must define these credentials in Onum: * `client_id` will reference your Box Client ID. * `client_secret` will reference your Box Client Secret. To do it, click **Add element** and enter a **Name** for the secret (in this case, `client_id`). Then, click the **Value** field and select **New secret** to create a new one: * Give the secret a **Name**. * Turn off the **Expiration date** option. * Click **Add new value** and paste the secret corresponding to the value. * Click **Save**. You can now select the secret you just created in the **Value** field list. Repeat the process for the `client_secret`. {% hint style="info" %} Learn more about secrets in Onum in [this article](/administration/global-settings/organization-settings/secrets-management.md). {% endhint %} ### Setup After entering the required parameters and secrets, you can choose to manually enter the rest of configuration fields, or simply paste the given YAML: {% tabs %} {% tab title="Config as YAML" %} Toggle this **ON** to enable a free text field where you can paste your **Box API** YAML. ```yaml withTemporalWindow: true temporalWindow: duration: 30s offset: 30s tz: UTC format: RFC3339 withAuthentication: true authentication: type: token token: request: method: POST url: https://api.box.com/oauth2/token headers: - name: Content-Type value: application/x-www-form-urlencoded bodyType: urlEncoded bodyParams: - name: grant_type value: client_credentials - name: client_id value: '${secrets.client_id}' - name: client_secret value: '${secrets.client_secret}' - name: box_subject_id value: 62685208 - name: box_subject_type value: enterprise tokenPath: ".access_token" authInjection: in: header name: Authorization prefix: 'Bearer ' suffix: '' withEnumerationPhase: false collectionPhase: paginationType: "cursor" cursorSelector: ".next_stream_position" initialRequest: responseType: json method: GET url: "https://api.box.com/2.0/events" headers: - name: Accept value: application/json queryParams: - name: stream_type value: admin_logs - name: created_after value: ${temporalWindow.from} - name: created_before value: ${temporalWindow.to} - name: limit value: '100' # REMOVED: event_type parameter - either remove entirely or use valid Box event types # Valid types: ACCESS_GRANTED, ADMIN_LOGIN, FILE_MARKED_MALICIOUS, etc. nextRequest: responseType: json method: GET url: "https://api.box.com/2.0/events" headers: - name: Accept value: application/json queryParams: - name: stream_type value: admin_logs - name: stream_position value: '${pagination.cursor}' - name: created_after value: ${temporalWindow.from} - name: created_before value: ${temporalWindow.to} - name: limit value: '100' output: select: ".entries" map: "." outputMode: "element" ``` {% endtab %} {% tab title="Manually configure" %} **Temporal Window** Toggle **ON** to add a temporal window for events. This repeatedly shifts the time window over which data is collected. * **Duration****\*** - `30s` * **Offset****\*** - `30s` * **Format****\*** - `RFC3339` **Authentication** Toggle **ON** to configure the authentication phase. * **Type****\***** -** `token` * **Token Retrieve Baes Authentication** * **Request** * **Method****\*** - `POST` * **URL****\*** - `https://api.box.com/oauth2/token` * **Headers** * **Name** - `Content-Type` * **Value** - `application/x-www-form-urlencodedapplication/x-www-form-urlencoded` * **Body Type****\*** - `urlEncoded` * **Body Params** * **Name** - `grant_type` * **Value** - `client_credentials` * **Name** - `Client ID` * **Value** - `${secrets.client_id}` * **Name** - `Client Secret` * **Value** - `${secrets.client_secret}` * **Name** - `box_subject_id` * **Value** - `62685208` * **Name** - `box_subject_type` * **Value** - `enterprise` * **Token path** - `.access_token` * **Auth injection** * **In****\*** - `header` * **Name****\*** - `Authorization` * **Prefix** - `'Bearer '` * **Suffix** - `''` **Collection Phase** Toggle **ON** to configure the collection phase. This API endpoint requires an initial request that will provide a list of alert ids. In order to get the details about that information, it will require an additional request for those details. * **Pagination Type****\*** - `Cursor` * **Cursor Selector****\*** - `.next_stream_position` * **Initial request** * **Response Type**\* - `JSON` * **Method****\*** - `GET` * **URL****\*** - `https://api.box.com/2.0/events` * **Headers** * **Name** - `Accept` * **Value** - `Application/JSON` * **Query Params** * **Name** - `stream_type` * **Value** - `admin_logs` * **Name** - `created_after` * **Value** - `${temporalWindow.from}` * **Name** - `created_before` * **Value** - `${temporalWindow.to}` * **Name** - `limit` * **Value** - `100` * **Next request** * **Response Type****\*** - `JSON` * **Method****\*** - `GET` * **URL****\*** - `https://api.box.com/2.0/events` * **Headers** * **Name** - `Accept` * **Value** - `Application/JSON` * **Query Params** * **Name** - `stream_type` * **Value** - `admin_logs` * **Name** - `stream_position` * **Value** - `${pagination.cursor}` * **Name** - `created_after` * **Value** - `${temporalWindow.from}` * **Name** - `created_before` * **Value** - `${temporalWindow.to}` * **Name** - `limit` * **Value** - `100` * **Output** * **Select****\*** - `.entries` * **Map** - `.` * **Output Mode****\*** - `element` {% endtab %} {% endtabs %} When you're done, click **Create labels** to move on to the next step and define the required [Labels](/the-workspace/listeners/labels.md) if needed. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.onum.com/the-workspace/listeners/listener-integrations/pull-data-from-http-endpoints/collect-data-from-box.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.