# Users

Collects directory user records from the runZero platform.

**Sync Type: Full Synchronisation**

## Authentication

This input supports two authentication methods.

**API Token** — Generate an Export API token (or Account API token) from the runZero console:

1. Log in to [console.runzero.com](https://console.runzero.com).
2. Navigate to **Account** > **API Tokens**.
3. Click **Generate** to create a new Export API token.
4. Copy the token value — you will need it when configuring the input in Monad.

> **Note:** Export API tokens provide read-only access to organization data. Use an Account API token only when an Export token is insufficient. Restrict the token to the minimum required scope.

**OAuth 2.0 (Client Credentials)** — Create an OAuth application in runZero:

1. Log in to [console.runzero.com](https://console.runzero.com).
2. Navigate to **Account** > **OAuth Applications**.
3. Create a new application and copy the **Client ID** and **Client Secret**.
4. Ensure the application has permission to read user/directory data for the target organization.

## Details

Monad uses the `cron` field to run this input on a schedule. On each run, the input fetches all user records from the `/export/org/users.json` endpoint for the configured organization, performing a full sync of data each time.

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

#### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| Organization ID | string | Yes | The UUID of the runZero organization to collect data from. |
| Authentication Method | one-of | Yes | Authentication method to use for accessing the runZero API. Choose between **API Token** and **OAuth 2**. |
| Cron | string | Yes | Cron expression defining how often to fetch user data. Example: `0 0 * * *` for daily at midnight. |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

#### Secrets (API Token method)

| Secret | Type | Required | Description |
|--------|------|----------|-------------|
| API Token | string | Yes | The runZero API token (e.g. an Export Token or Account API Token). |

#### Secrets (OAuth 2 method)

| Secret | Type | Required | Description |
|--------|------|----------|-------------|
| Client ID | string | Yes | The OAuth 2.0 client ID for the runZero application. |
| Client Secret | string | Yes | The OAuth 2.0 client secret for the runZero application. |

## Rate Limits

runZero does not publish a specific rate limit for the Export API. If you encounter rate-limiting errors, increase your cron interval to reduce request frequency. See the [runZero API documentation](https://www.runzero.com/docs/leveraging-the-api/) for the latest guidance.

## Custom Schema Handling

If the source data doesn't align with any of the [OpenSecurityControlFramework (OSCF) schemas](https://schema.ocsf.io/), you can create a custom transformation using our JQ transform pipeline. For example:

```jq
{
  metadata: {
    schema_version: "1.0.0",
    custom_framework: "my_framework"
  },
  controls: .[]
}
```

For more information on JQ and how to write your own JQ transformations see the JQ docs [here](https://jqlang.github.io/jq/).

If you believe this data source should be included in the standard OSCF schema set, please reach out to our team at [support@monad.com](mailto:support@monad.com). We're always looking to expand our coverage of security control frameworks based on community needs.

## Related Articles

- [runZero API Documentation](https://www.runzero.com/docs/leveraging-the-api/)
- [runZero Export Tokens](https://help.runzero.com/docs/leveraging-the-api/#authentication)
- [runZero Organizations](https://www.runzero.com/docs/organizations/)

## Sample Record

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "site_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "site_name": "HQ",
  "org_name": "Example Organization",
  "source": "activedirectory",
  "name": "jdoe",
  "display_name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "email": "jdoe@corp.example.com",
  "phone": "+1-555-555-0100",
  "title": "Senior Engineer",
  "location": "New York",
  "description": "IT department member",
  "last_logon_at": 1746921600,
  "first_seen_at": 1746921600,
  "last_seen_at": 1746921600
}
```

## Sync frequency

This input runs on a cron schedule (default hourly, `0 * * * *`), which you can configure on the pipeline. See [Input Sync Frequency](../../guides/sync-frequency) for details.