How to Authenticate to the Red Canary API

Issue

A user is attempting to authenticate to the Red Canary API and having difficulties with authentication or formatting requests.

Environment

Red Canary API v3

Resolution

Table of Contents

• Quick Start
• Generate Your API Key
• Construct Your Request
• Authenticate Your Request
• Make Your Request
• Troubleshooting

Quick Start

To help you get started with the Red Canary API, below is a sample request that returns the first page of 10 Windows endpoints in your subdomain. This is a valid cURL request, though the <angled bracket> values need to be replaced with your own, and the brackets removed.

curl --request GET \
  --url https://<MySubdomain>.my.redcanary.co/openapi/v3/endpoints?per_page=10&filter_query=platform:Windows&page=1 \
  --header 'x-api-key: <MyRedCanaryKeyHere>'

Follow the information on this page for a detailed breakdown on authenticating and crafting your API requests.

Generate Your API Key

The Red Canary API is authenticated using API Keys. In order to access data via the API, you must first generate an API key in the Red Canary Portal. Permissions available to API Keys are limited to the User Roles of user generating the key.

For more information about User Roles, see Understand and Assign Roles.

Construct Your Request

The request URL uses the structure below.

• Base URL (https://<MySubdomain>.my.redcanary.co/)
• API Version (openapi/v3/)
• API Endpoint The specific endpoint hosting the data being requested (see Red Canary API Docs)
• Parameters (optional) Ampersand-delimited Parameters (see Red Canary API Docs)

Red Canary Portal Address / OpenAPI / v3 / API Endpoint (optional: ? Parameters)

Base URL

The Base URL is the same URL of your Red Canary Portal (i.e. https://<MySubdomain>.my.redcanary.co/). Your API key will work with all Red Canary subdomains that are linked to your user profile. Similarly, if you reset your API key, the key is no longer valid across subdomains you are linked to.

API Endpoints

For a list of the latest available API Endpoints, refer to the Red Canary API Swagger Documentation.

Parameters

Available parameters will vary based on the API method and endpoint used in your request. Refer to the endpoints in our Red Canary API Swagger Documentation for available parameters. Some parameters, like filter_query, only support one filtered value. If you need to apply multiple filter_query parameters, consider using a Post Response script to further filter.

Authenticate Your Request

The Red Canary API requires a custom header name for API Key authentication, called X-API-Key. This authentication method uses your API key from the Red Canary Portal in your request headers.

--header 'x-api-key: <MyRedCanaryKeyHere>'

If using an API utility, like Postman, select API Key as your Auth method and use X-API-Key as the Key name. The value is your API Key.

Make Your Request

At this point, you should have all the information needed to complete the template cURL request below.

curl --request GET \
  --url <Base URL>/openapi/v3/<API Endpoint>?<Optional Parameters> \
  --header 'x-api-key: <API Key>' \
  --header 'content-type: application/json'

Troubleshooting

Common Error Codes

• 400 Bad Request: A malformed or invalid parameter is being used in your request.
• 403 Forbidden: See 403 Forbidden Error Authenticating to Red Canary API
• 404 Not Found: See 404 Not Found Error from Red Canary API
• 405 Not Allowed: The API Endpoint does not support the request method in use (e.g. POST, PATCH, DELETE, etc.)
• 429 Too Many Requests: See 429 Too Many Requests Error from Red Canary API
• 500 Internal Server Error: An unexpected error occurred within Red Canary. Ensure your parameters match expected values type (i.e. integer, string, etc.). Check our status page for any degraded services and try again later. Reach out to Red Canary Support if the issue persists.
• 503 Unavailable: The endpoint or service is temporarily unavailable. Check our status page for any degraded services and try again later. Reach out to Red Canary Support if the issue persists.

Additional Troubleshooting Tips

• If using templates from this article or elsewhere in Red Canary documentation, ensure values are substituted correctly and brackets removed
• If receiving 403 errors, have the API Key owner log into Red Canary Portal and verify they can access or modify the desired data via the web console. If the data is missing or unavailable, they may not have an appropriate User Role assigned.
• When troubleshooting complex requests or scripts, simplify and validate the core request is viable then evaluate parameters or script functions individually.
• If using multiple filter_query parameters in a request, only the last one will be evaluated.