Using the Hyperproof APIs

The Hyperproof APIs allow developers to read and write Hyperproof data on behalf of a user.  Your third party application can use these APIs to retrieve the controls and labels in a Hyperproof organization, create new controls and labels, and also to upload proof.  In the future additional extensibility scenarios will also be enabled.

Because all API requests operate on behalf of an active Hyperproof user, all requests must include authentication information.  The sections below provide information on obtaining and providing this authentication information.

Authentication

Every HTTP request made to the Hyperproof APIs must be authenticated by Hyperproof.  Hyperproof uses OAuth 2.0 as the primary means for request authentication.

Using OAuth 2.0

OAuth 2.0 allows applications to obtain access to Hyperproof resources such as the Controls, Labels or Proof in an organization.

The following sections will provide an overview of the OAuth protocol and how it is used with the Hyperproof API.

OAuth Roles

The OAuth protocol defines four specific roles and these roles are actively involved in the process of authentication flow with Hyperproof APIs:

  • Resource Owner: The resource owner is an active Hyperproof user who can either authorize or decline a Client from accessing information in a Hyperproof organization.

  • Authorization Server: The authorization server is responsible for authenticating the user and allowing them to consent to API access.  The authorization server also provides access tokens and refresh tokens. 

  • Resource Server: The resource server is the server that is hosting the resource. If your application is integrating with the Hyperproof API to obtain data that resides in a Hyperproof organization, the Hyperproof API server is considered the resource server.

  • Client: The client is the application that requests access to the user’s information. If your app makes access requests to the Hyperproof API, your app is considered as the Client.

Note: In this document, you will see the term “Client” and “app” being used interchangeably. Both of these terms refer to the app that needs to integrate with the Hyperproof API.

OAuth Grant Types

OAuth 2.0 supports various grant types. With the Hyperproof APIs you can use either the authorization code grant type or the client credentials grant type.

If you are building an app that is designed to work on any Hyperproof organization, or if your app requires that a user authorize access to their information in a Hyperproof organization, the authorization code flow should be used. See OAuth Authorization Code Flow for more information.

If you are building an app that targets a specific Hyperproof organization, or if are building a machine-to-machine app (such as CLIs, daemons, or services running on your back-end), the client credentials flow should be used. See OAuth Client Credentials Flow for more information.

Both of these OAuth flows will generate an access token that you will need to include in your API requests.

API Requests

All API requests must be made over HTTPS. The base URL for the request is https://api.hyperproof.app/v1/. The complete URL varies depending on the resource being accessed.

For instance, to list all of the controls in an organization, you must make an HTTP GET request to this URL: https://api.hyperproof.app/v1/controls. For this API to succeed, your app must have the control.read scope.

See the APIs Page for a complete list of the supported APIs along with examples.

The access token retrieved through the OAuth 2.0 authorization code flow or the client credentials flow must be included in each request using the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXIiOiIxLjAiLCJpc3...