Enabling M2M API authentication
Roles and permissions
Only administrators can enable M2M API authentication for the organization
Hyperproof supports two API client types: service account and personal.
Service account API clients allow Hyperproof administrators to create an API client for a shared service account, whereas personal API clients allow any user, regardless of their role in Hyperproof, to create an API client using their own personal credentials.
The API client has an associated service principal and accesses the API client using that service principal’s credentials.
When calling a Hyperproof API, the caller must pass as an owner when creating a new object, e.g. a control. Hyperproof has checks in place around this field to ensure that this service principal is never an assignee or owner for any object. This is to ensure that any object with responsibilities or actions attached is always associated with at least one human user.
All Hyperproof administrators can create, view, edit, and delete any of the service account API clients in their organization. There is no limit to the number of service account API clients an administrator can create, nor is there a limit to the amount of service account API clients an organization can have.
To create a service account API client in Hyperproof:
Only Hyperproof administrators can create, view, edit, and/or delete service account API clients.
From the left navigation menu, select Settings.
Select API clients.
Select the Service account tab, and then click New.
The New API client window opens.
Below Name, enter a name for the API client.
Below Client ID, click the Copy to clipboard icon.
Note
The 32-character client ID is automatically generated when the New API client window opens. If the transaction is canceled, the client ID is discarded. If the transaction is saved, the client ID becomes associated with this API client.
From the Scopes drop-down menu, select at least one scope that the API client should be granted permission to access. When creating or editing an API client, a user can only grant permissions equal to or less than their own permissions. Note that this drop-down menu is populated with the same permissions as the service principal role.
From the Role drop-down menu, select the Hyperproof role for the API client:
Admin - Manages the organization, its compliance managers, and its users; can create and join objects in the organization without needing permission
API admin - Can retrieve all data fields across all records; for use with the Hyperproof API only
Compliance manager - Can create and manage new programs in the organization
User - Can read and list objects in an organization
External auditor - Can only view and interact with audits they've been explicitly added to
Below Client secret, click the Copy to clipboard icon.
Note
Do not skip this step! Client secrets cannot be viewed again once the New API client window is closed.
Optionally, enter a description of the API client.
Optionally, below Expiration date, enter the date the client secret should expire. By default, the client secret expires six months from the date of creation.
Optionally, click New secret to create an additional client secret.
Tip
An API client can have multiple secrets to allow for smooth secret rotation.
Click Save. The API client is created.
Tip
Click Edit to refine the API client at any time.
Any user can create, view, and/or edit their own personal API client, regardless of their permissions in Hyperproof. Only the user who created the personal API client can create, view, and/or edit it. Users cannot view other users’ personal API clients.
To create a personal API client in Hyperproof:
Personal API clients automatically match the role of the user who creates it, e.g. if a compliance manager creates the personal API client, the client will assume the role of a compliance manager.
From the left navigation menu, select Settings.
Select API clients.
Select the Personal tab, and then click New.
The New API client window opens.
Below Name, enter a name for the API client.
Below Client ID, click the Copy to clipboard icon.
Note
The 32-character client ID is automatically generated when the New API client window opens. If the transaction is canceled, the client ID is discarded. If the transaction is saved, the client ID becomes associated with this API client.
From the Scopes drop-down menu, select at least one scope that the API client should be granted permission to access. When creating or editing an API client, a user can only grant permissions equal to or less than their own permissions.
Below Client secret, click the Copy to clipboard icon.
Note
Do not skip this step! Client secrets cannot be viewed again once the New API client window is closed.
Optionally, enter a description of the API client.
Optionally, below Expiration date, enter the date the client secret should expire. By default, the client secret expires six months from the date of creation.
Optionally, click New secret to create an additional client secret.
Tip
An API client can have multiple secrets to allow for smooth secret rotation.
Click Save. The API client is created.
Tip
Click Edit to refine the API client at any time.