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

Export and Organization APIs

Export API tokens and Organization API keys can be generated from the Organizations section in the runZero web console. You must have administrator access to generate API keys.

From the Organizations page, click on the desired organization to view its details page. Then, click Edit organization and scroll down to the export tokens or API tokens section to locate the Generate button for the type of API key you want to generate. Clicking the button will generate a secure API key in the form of a long random token.

Account API

Platform

Account API keys require an Platform license and are generated from the Account settings page. To use an Account API key or token with the Organization or Export API, specify the additional parameter _oid=[organization-id] in the query parameters.

API client credentials

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. Register an API client and use the client ID and client secret to generate an access token as shown in the following 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

Once you have generated an API key or access token, your REST client should use it with the Authorization: Bearer standard header to authenticate.

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.

Additional documentation

Please see the Swagger documentation and runZero OpenAPI specification for details on the individual API calls.