Before You Start Using the API

This document provides important information about preparing to use the Corastone Integration API. It has the following sections:

• Whitelisting Requirements

• Client-Specific Connection Information

• API Clients

• Supporting Documents

If you need support while preparing to use the API, contact us:

• via direct contact with the Corastone Onboarding team

• by email at [email protected]

Whitelisting Requirements

To enable Corastone access, the following actions must occur as described below:

• Client networking team must whitelist Corastone API URL.

• Client networking team must whitelist Corastone IP addresses.

• Client must provide IP address ranges to Corastone for systems and developer access.

Summary

The following table outlines the whitelisting tasks required for API use.

Task	Traffic Direction	Performed By
Whitelist Corastone API URL & domain (Outbound)	Client -> Corastone	Client Firewall Team
Whitelist Corastone IPs (Inbound)	Corastone -> Client (REST)	Client Firewall Team
Whitelist Client Source IPs	Corastone -> Client	Corastone
Test API Access	Client <-> Corastone	Client

The following sections detail each task.

Whitelist Corastone API URL & Domain Outbound

You must allow outbound traffic by whitelisting one of the following:

• the full Integration API URL (provided in Client-Specific Connection Information)

OR

• the wildcard domain *.idevit.us (covers all Corastone API endpoints)

Whitelist Corastone IPs Inbound

To receive Corastone push REST notifications, you must:

• whitelist Corastone static IPs for inbound access (provided in Client-Specific Connection Information)

Whitelist Client Source IPs

To enable us to accept API requests from the Client, you must:

• send Corastone the public IPs that will initiate API calls (one or more public IP addresses)

Corastone will whitelist them internally and allow the connections.

Test API Access

When all whitelisting tasks have been performed, test access to the Corastone APIs:

• Set up an API client (such as Postman or Insomnia) for testing.

• Set the User-Agent header for the API client.

• Review other header settings in the API collection you received from Corastone to ensure other headers are set appropriately.

• Review the Baseline Rule Groups for AWS for possible connectivity issues.

• Execute the following endpoint with an API client to get a token:

https://integration-api.<org_id>.cdev.idevit.us/oauth2/token

where <org_id> is the org id listed in Client-Specific Connection Information.

See Client Specific Connection Information for values needed when executing this endpoint.

Troubleshooting

403 Forbidden

• Make sure the User-Agent header is set.

• Work with your firewall team to determine if their configuration is compatible with the baseline AWS rules: Baseline Rule Groups for AWS.

Error: getaddrinfo ENOTFOUND integration-api.<org_id>.cdev.idevit.us

• Make sure org_id is correct.

If this test is unsuccessful, please contact the Corastone Onboarding team for assistance.

---

Client-Specific Connection Information

You will need the following information from the Corastone Onboarding Team:

Integration API URL:

Org ID:

Client ID:

Client Secret:

Org Static IP 1:

Org Static IP 2:

---

API Clients

The Corastone APIs work with several API clients such as Insomnia and Postman. Corastone may be able to provide API collections for API clients upon request.

---

Supporting Documents

Integration API Guide

This guide fully describes the use of the Corastone APIs and includes links to more technical information in Swagger.