# How to Succeed with the Hypersync SDK

# Define your proof

First, familiarize yourself with how Hyperproof organizes the data it collects through Hypersync so you understand what that data looks like when it appears in a Hyperproof “proof” document. Then identify what information you want to collect from the third-party system, which specific data fields you want to include, and how you want that information organized into separate Hyperproof proof types. Each proof type is collected by a separate Hypersync that you configure in Hyperproof.

If you or your team has already been collecting proof from a system manually, it can be very useful to review an existing example and understand how that proof has been used to demonstrate compliance in the past. Try to identify the following:

* **Different kinds of proof**: Each one will likely map to a different proof type. For example, if you use a security scanner, you might need one proof type for the scanner’s configuration settings and another for scan results.
* **Key pieces of information included in each proof type**: For example, if you have a policy that requires MFA, make sure the user list from your identity management system includes MFA status.


# Validate the API

Next, verify that the third-party app’s APIs support the data you want to include in your proof.

Here are a few ways to try out an API:

* Look for a “Try It” button in the documentation.
* Follow the documentation’s recommendations. Some APIs point you toward tools like Postman, while others use browser-based tools. Postman is especially useful to learn if you plan to build Hypersyncs for multiple apps.


API details to watch for:

* Some products offer query or reporting APIs that are especially powerful. Jira and Salesforce are good examples of apps that let users build queries. Proof types based on these APIs are appealing because a single proof type can pull almost any data stored in the app.
* Some products have multiple APIs that cover different parts of the product and may behave differently. For example, some vulnerability scanners provide one API for real-time behavior and another for long-term reporting. For Hypersyncs, you’ll generally want the reporting option.
* Some products use different APIs for different SKUs, such as an older enterprise offering versus a newer cloud version.
* Some features may not be available to all customers—for example, custom roles might only be included in enterprise SKUs that require more granular control.


The key thing to accomplish in this stage is whether the API supports the collection of all the fields that you need for your hypersync and your proof.

Once you’re confident you have the right API for your proof, capture a few key details:

* **Minimum permissions required to call the API.** At some point, an IT admin will need to provision a service account or user with the minimum permissions needed for your integration. Hypersyncs are read-only, so when an app offers read-only permissions, you should use them. Tracking which proof types require which permissions from the start is much easier than trying to piece it together later.
* **Minimum scopes required for authorization (OAuth only).** The Hypersync author will be asked to authorize one or more scopes, so you should only request what you need. Hypersyncs are read-only, so when an app offers read-only scopes, you should use them.
* **API and documentation URLs.** You’ll need the API URL to make requests, and it’s also helpful to include a link to the documentation in the dataset definition.


# Authentication

Once you understand what you’re trying to build, you’re ready to explore the APIs and choose the ones you’ll use. Most systems publish API documentation, and the Hypersync SDK works best with REST and GraphQL-based APIs, so look for those if possible.

One of the first things you’ll need to figure out is authentication. Most documentation covers this early, so you shouldn’t have to search far. The Hypersync SDK supports two types of authentication:

* **OAuth Authorization Code Flow**
This common flow asks the end user to authorize Hyperproof to perform specific actions on their behalf. Behind the scenes, Hyperproof exchanges that authorization for an access token used to make API calls. The user only needs to complete this flow once.
* **Custom Auth**
Custom auth includes any authentication model where the user provides credentials to create a connection. Credentials might include a username and password, an access key and secret key, and more. Users may also need to specify the endpoint they’re connecting to—for example, by providing a URL or selecting a region.


Some systems support multiple authentication options, and you may be able to choose between them. Look for methods that support the APIs you plan to use (you may need to skim ahead and circle back) and that work with service accounts. Also watch for older authentication methods that are being phased out in favor of newer ones.

Service accounts let you authenticate to a service without tying the integration to a specific person. We recommend using service accounts for Hypersyncs so integrations don’t break when someone changes jobs—or wins the lottery. Service accounts also make IT admins happier because they can be managed and monitored independently from end-user accounts.

# Skills

Here's a list of the essential skills required for a developer to be successful creating a hypersync using the SDK.

* Node.js + TypeScript/JavaScript experience
* Working knowledge of REST APIs (pagination, rate limits, retries, error handling)
* Strong grasp of auth (OAuth and/or API key flows) and token management
* Ability to work with JSON-based configuration/mapping
* Local setup: Node 18, Yarn classic (1.22.x), Hyperproof CLI, .NET 8 runtime
* Confidence debugging with logs + API traces (CLI logs, browser network tools)


# Development environment

On the tooling side, plan to develop with Node.js 18, Yarn classic (1.22.x), and the Hyperproof CLI for importing and updating your app in a Hyperproof org. You’ll also need the .NET 8 runtime installed for the CLI to run. Hypersync developers should have all of these installed and working before choosing a template and starting development. Links to the required packages are available in the SDK documentation.

The SDK Samples repository includes four starter templates, and it’s important to choose the right one. The templates support different authentication methods and custom data source types, and each template folder name corresponds to the appropriate auth and data source type it’s designed for.