Leveraging the 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.
API keys and tokens
The console supports five types of runZero API key, with different levels of access to runZero APIs.
Export tokens
An export token only allows access to export data via the export API endpoints 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
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. 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
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.
Account API client credentials are managed from the API clients page. Your REST client should use the OAuth 2.0 authorization type and Client Credentials grant type. See the OpenAPI specification 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 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" \
-d "grant_type=client_credentials&client_id=<CLIENT_ID>&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 APIX-API-Usage-Today- Number of calls made to the API todayX-API-Usage-Limit- Your daily API call limit, shared across all API keysX-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.
Additional documentation
Please see the Swagger documentation and runZero OpenAPI specification for details on the individual API calls.