---
title: "Leveraging the API"
aliases: [ "/docs/organization-api/" ]
---

runZero provides three primary APIs as well as integration-specific endpoints:

* The ((Export API)) provides read-only access to a specific organizations.
* The ((Organization API)) provides read-write access to a specific organizations (Professional and Platform licenses).
* The ((Account API)) provides read-write access to all account settings and organizations (Platform license).

To get started, you will need an ((API key)) / ((token)) or ((API client credentials)). 

<iframe src="https://demo.arcade.software/SHgu7YOmaQMJXbhkxWFT?embed" loading="lazy" allowfullscreen title="Walkthrough - Creating API Keys"></iframe>

## API keys and tokens

The console supports five types of runZero API key, with different levels of access to runZero APIs. As an additional security option around API access, runZero allows users to create an IP address allowlist to restrict API access based on IP addresses and network ranges (in CIDR notation).

### Export tokens

An ((export token)) only allows access to export data via the [export API endpoints](https://console.runzero.com/inventory/export_api) under the `/api/v1.0/export` path. It cannot access any other APIs.

An export token has information about its organization encoded into it. It can only be used to export data for that organization. There is no need to specify the organization when using an export token.

Export tokens can be recognized by their `ET` prefix.

To generate an export token, go to the Organizations page, click on the desired organization to view its details page. Then, click **Edit organization** and scroll down to the export tokens section and use the button to generate or regenerate the token.

### Download tokens

A ((download token)) allows access to download the runZero Explorer. This can be useful if you want to automate downloads for deployment across many machines, or if you need to containerize the Explorer. It cannot be used to access any other API.

Like export tokens, the download token has information about the organization encoded into it. This determines the organization the downloaded Explorer will be associated with.

Download tokens can be recognized by their `DT` prefix.

To obtain the download API token, go to the Organizations page, click on the desired organization to view its details page. Then, click **Edit organization** and scroll down to the download token section.

### Organization API tokens

An ((organization API token)) allows read and write access to data within a particular organization, using the organization API. Most of the organization endpoints are under the `/api/v1.0/org` path. Organization tokens can also be used to access the export APIs.

An organization API token has information about the organization encoded into it. It can only be used to access that organization. There is no need to specify the organization when making a call using an organization API token.

Organization API tokens can be recognized by their `OT` prefix.

To generate an organization API token, go to the Organizations page, click on the desired organization to view its details page. Then, click **Edit organization** and scroll down to the organization API tokens section. You can use the buttons to generate named organization API tokens and revoke them.

### Account API tokens

<!-- licenses: platform -->

An account API token allows read and write access to the account API endpoints. These provide access to perform account-level operations such as creating and deleting organizations and users. Account API tokens can also be used for organization level access and for the export API.

Account API tokens require a Platform license and are generated from the [Account settings page](https://console.runzero.com/account). To use an account API token with the Organization or Export API, specify the additional parameter `_oid=[organization-id]` in the query parameters.

An account API token has no specific organization encoded into it. When using an account API token with an API call that applies to an organization, the organization must be specified. This can be done by appending an `_oid` value to the URL query parameters. The `_oid` should be the unique ID of the organization. This can be found on the organization's information page.

Account API tokens can be recognized by their `CT` prefix (((client token))).

To generate an account API token, go to the Account settings page under Account in the left navigator. You can create and delete account API tokens as needed.

### API client credentials

<!-- licenses: platform -->

The organization and account tokens above are used as bearer tokens for API access. The API client credentials are different; they are used to obtain account API tokens programmatically, via [OAuth2](https://auth0.com/intro-to-iam/what-is-oauth-2).

Account API client credentials are managed from the [API clients page](https://console.runzero.com/account/api/clients). Your ((REST)) client should use the OAuth 2.0 authorization type and Client Credentials grant type. See the [OpenAPI specification](https://github.com/runZeroInc/runzero-api) for the access token details.

## Authentication

Once you have a token or some API client credentials, you can authenticate against the runZero API.

For export, organization and account tokens, your ((REST)) client should use the token with [the `Authorization: Bearer` standard header](https://swagger.io/docs/specification/authentication/bearer-authentication/) to authenticate.

For API client credentials, you must use the generated client ID and client secret to make an OAuth2 call to generate an access token. For example:

```
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<CLIENT_ID>" \
  --data-urlencode "client_secret=<CLIENT_SECRET>" \
  https://console.runzero.com/api/v1.0/account/api/token
```

## API rate limiting

API calls are rate limited. You can make as many API calls per day as you have licensed assets in your account. For example, if you have 1,000 licensed assets, you can make 1,000 API calls per day. Each API call returns rate limit information in the HTTP headers of the response:

- `X-API-Usage-Total` - Total number of calls made to the API
- `X-API-Usage-Today` - Number of calls made to the API today
- `X-API-Usage-Limit` - Your daily API call limit, shared across all API keys
- `X-API-Usage-Remaining` - The number of API calls remaining from your daily limit

In addition, there's a limit of 2,000 requests per 5 minutes per source IP address. If this is exceeded, an HTTP 429 response will be sent with an error of "request limit exceeded", and your client code should delay the next request.

## IP Address Allowlist

As an additional security option around API access, runZero allows users to create an IP address allowlist to restrict API access based on IP addresses and network ranges (in CIDR notation). Users can access this configuration from the Account Settings section of their console under a setting called "API key IP address allowlist".

This field accepts a comma-separated list of both IPv4 and IPv6 IP addresses and network ranges (in CIDR notation) and applies to all API usage across the console. An empty allowlist will result in the allowlist functionality being disabled and allowing all IP addresses to access the API.

## runZero API usage examples

This guide demonstrates how to use `curl` with the **runZero APIs**, including the **Organization API** for creating scan tasks and the **Export API** for retrieving data.

### Scan API usage

You'll need:

* An **Organization API token** (prefixed with `OT`)
* The **Site ID** where you want scan results to be stored

#### Set environment variables

First, set your Organization API token and Site ID as environment variables:

```bash
export RUNZERO_ORG_TOKEN="OT-YOUR-API-TOKEN-HERE"
export YOUR_SITE_ID="YOUR-SITE-ID-HERE" # Replace with the actual Site ID
```

#### API endpoint

The API endpoint to start a scan task within a specific site is:

```
PUT /api/v1.0/org/sites/{site_id}/scan
```

Example base URL:

```
https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan
```

#### Create a scan task for a specific Explorer

To run a scan on a **specific Explorer**, use the `"explorer"` property in the JSON payload with the Explorer’s UUID.

```bash
curl -X PUT "https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${RUNZERO_ORG_TOKEN}" \
  -d '{
    "explorer": "<YOUR-EXPLORER-ID>",
    "targets": "192.168.1.0/24",
    "scan-name": "Scan via Specific Explorer",
    "rate": "3000"
  }'
```

#### Create a scan task using a hosted Explorer

To run an external scan using a **runZero hosted Explorer**, use the `"hosted-zone-name"` key.

* Set `"hosted-zone-name": "auto"` to let runZero choose the best hosted zone.
* You can also specify a specific hosted zone name.
* Targets must be **public IP addresses or hostnames**.

```bash
curl -X PUT "https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${RUNZERO_ORG_TOKEN}" \
  -d '{
    "hosted-zone-name": "auto",
    "targets": "example.com",
    "scan-name": "Scan via Hosted Zone",
    "rate": "1000"
  }'
```

#### Create a scan task for an Explorer group

To distribute a scan task among a **group of Explorers**, use the `"explorer-group-id"` key with the Explorer group's UUID.
The group will automatically select an available Explorer to run the task.

```bash
curl -X PUT "https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${RUNZERO_ORG_TOKEN}" \
  -d '{
    "explorer-group-id": "<YOUR-EXPLORER-GROUP-ID>",
    "targets": "10.0.0.0/8",
    "scan-name": "Scan via Explorer group",
    "rate": "1000"
  }'
```

#### Additional notes

* The payloads above are **minimal working examples**.
* You can include any additional valid parameters, such as:

  * `"scan-template"`
  * `"tcp-ports"`
  * `"udp-ports"`
  * `"max-hosts"`
  * `"max-duration"`
  * `"probes"`
* Always validate your payload against your organization’s scan configuration and API schema.

### Export API usage

The **Export API** provides read-only access to your organization’s data, such as assets, sites, and scans.
It uses an **Export Token** (prefixed with `XT`) and is ideal for integrations or reporting that don’t modify data.

#### Set environment variables

```bash
export RUNZERO_EXPORT_TOKEN="XT-YOUR-EXPORT-TOKEN-HERE"
```

#### Base endpoint

All export endpoints use the `/api/v1.0/export/org/` path.

Example:

```
https://console.runzero.com/api/v1.0/export/org/assets.json
```

#### Export all assets (JSON)

Retrieve all assets in JSON format:

```bash
curl -X GET "https://console.runzero.com/api/v1.0/export/org/assets.json" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o assets.json
```

#### Export all assets (CSV)

Retrieve the same data in CSV format:

```bash
curl -X GET "https://console.runzero.com/api/v1.0/export/org/assets.csv" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o assets.csv
```

#### Export sites list

List all sites in your organization:

```bash
curl -X GET "https://console.runzero.com/api/v1.0/export/org/sites.json" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o sites.json
```

#### Export scans

Retrieve a list of completed scans:

```bash
curl -X GET "https://console.runzero.com/api/v1.0/export/org/scans.json" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o scans.json
```

#### Notes on export tokens

* **Export tokens are read-only** — they cannot modify organization data.
* They can be safely scoped to limit data access.
* Output may be large for organizations with many assets — consider filtering.
* You can use the `search` query parameter to filter exports, for example:

  ```bash
  curl -X GET "https://console.runzero.com/api/v1.0/export/org/assets.json?search=alive:true" \
    -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}"
  ```

## Additional documentation

Please see the [Swagger documentation](https://app.swaggerhub.com/apis/runZero/runZero/) and [runZero OpenAPI specification](https://github.com/runZeroInc/runzero-api) for details on the individual API calls.