Skip to content
/
Working with Scoped Contr...
Last updated

Working with Scoped Controls

This article explains how to create scopes, assign controls to scopes (including hierarchical ones), list scoped controls, and manage assignments using the Hyperproof API. It provides a plain-language overview of the official API documentation for the Scopes API, Scope Assignments API, and Controls API, with practical, original examples to help you implement each step. Scoped controls allow you to associate compliance controls with organizational hierarchies like business units or regions, enabling targeted oversight.

Creating a Scope

POST https://api.hyperproof.app/v1/scopes

  • Creates a new scope and returns its details, including id, pathIds (hierarchical path), and pathNames.
  • For hierarchical scopes, specify parentId to nest under an existing scope.

Sample

curl --request POST \
  --url https://api.hyperproof.app/v1/scopes \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Legal Department",
    "owner": "82d7c228-8bcd-11e9-a94b-ab3de8494987",
    "description": "Scope for legal team compliance"
  }'

With parent for hierarchy

PARENT_SCOPE_ID=cb1a06f4-8ed9-4614-a17b-f8671194687e
curl --request POST \
  --url https://api.hyperproof.app/v1/scopes \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Legal - Europe",
    "owner": "82d7c228-8bcd-11e9-a94b-ab3de8494987",
    "parentId": "'$PARENT_SCOPE_ID'",
    "description": "European legal sub-scope"
  }'

Listing Scopes (organization-wide)

GET https://api.hyperproof.app/v1/scopes

  • Returns a list of scopes with details like id, name, owner, parentId, pathIds, and pathNames (for hierarchy).
  • Use for discovering scopes before assignments.

Filtering

  • status (string, optional) - Filter by status (e.g., active, archived).

Sample

curl --silent \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.hyperproof.app/v1/scopes?status=active"

Response example

[
  {
    "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
    "name": "Legal Department",
    "owner": "82d7c228-8bcd-11e9-a94b-ab3de8494987",
    "description": "Scope for legal team compliance",
    "parentId": null,
    "pathIds": ["cb1a06f4-8ed9-4614-a17b-f8671194687e"],
    "pathNames": ["Legal Department"]
  }
]

Creating Scope Assignments (linking controls to scopes)

POST https://api.hyperproof.app/v1/scopeassignments

  • Associates controls (or other objects) with one or more scopes, creating "scope assignment" controls if needed.
  • Returns assigned objects with updated details, including controlType: "scopeAssignment" and scopeName.
  • Supports bulk assignments for efficiency.

Sample (assign one control to two scopes)

CONTROL_ID=6c006c16-9349-4df2-80be-64895c27d7bb
SCOPE_ID_1=2128c0da-140e-460d-974c-8cd20401afbc
SCOPE_ID_2=ef11b12c-3b75-4a19-b212-72dcbe010fe7
curl --request POST \
  --url https://api.hyperproof.app/v1/scopeassignments \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "[
    {
      \"objectType\": \"control\",
      \"objectId\": \"$CONTROL_ID\",
      \"scopeIds\": [\"$SCOPE_ID_1\", \"$SCOPE_ID_2\"]
    }
  ]"

Bulk assignment (multiple controls)

curl --request POST \
  --url https://api.hyperproof.app/v1/scopeassignments \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "[
    {
      \"objectType\": \"control\",
      \"objectId\": \"control-1-uuid\",
      \"scopeIds\": [\"scope-1-uuid\"]
    },
    {
      \"objectType\": \"control\",
      \"objectId\": \"control-2-uuid\",
      \"scopeIds\": [\"scope-1-uuid\", \"scope-2-uuid\"]
    }
  ]"

Response example

{
  "controls": [
    {
      "id": "d88d505d-5199-11ee-a644-522476618ae8",
      "controlType": "scopeAssignment",
      "controlIdentifier": "SOC2-P4.1.1_Legal",
      "name": "Include in the privacy notice the use of collected personal information",
      "scopeName": "Legal"
    }
  ]
}

Listing Controls with Scope Expansions

GET https://api.hyperproof.app/v1/controls

  • Retrieves controls; with expandScopes=true, includes hierarchical scope info like scopeName and child assignments.
  • Useful for viewing scoped controls in context.

Parameters

  • expandScopes (string, optional) - Set to true to include scope-assigned controls and parent details.
  • status (string, optional) - Filter by status (e.g., active).
  • canLink (string, optional) - Set to true for controls the user can link to.

Sample (with scope expansion)

curl --silent \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.hyperproof.app/v1/controls?expandScopes=true&status=active"

Filtered by linkable scopes

curl --silent \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.hyperproof.app/v1/controls?canLink=true&expandScopes=true"

Getting the Scope Tree (hierarchical view)

POST https://api.hyperproof.app/v1/scopes/tree

  • Returns a nested tree structure of scopes, including children and paths.
  • Ideal for visualizing hierarchies before assignments.

Body

  • onlyActive (boolean, optional) - Set to true to filter active scopes only.

Sample

curl --request POST \
  --url https://api.hyperproof.app/v1/scopes/tree \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"onlyActive": true}'

Response example (snippet)

{
  "scope": {
    "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
    "name": "Legal Department",
    "children": [
      {
        "id": "71f5fba2-bd08-4e7e-9e6c-05209956f22d",
        "name": "Legal - Europe",
        "pathNames": ["Legal Department", "Legal - Europe"]
      }
    ]
  }
}

Updating a Scope or Assignment

PATCH https://api.hyperproof.app/v1/scopes/{scopeId} (for single scope) or PATCH https://api.hyperproof.app/v1/scopes (bulk)

  • Updates scope details; re-POST to /scopeassignments to adjust assignments.
  • Use Controls API PATCH for updating assigned control properties like owner or freshness.

Body

  • For single: Body with name, owner, description, status (e.g., archived), customFields.
  • For bulk: {"scopeIds": ["id1", "id2"], "patch": {updates}}.

Sample (update single scope)

SCOPE_ID=cb1a06f4-8ed9-4614-a17b-f8671194687e
curl --request PATCH \
  --url "https://api.hyperproof.app/v1/scopes/$SCOPE_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Legal Department Updated",
    "status": "active"
  }'

Response Fields (common)

While the exact shape can evolve, responses commonly include:

  • id (UUID) - Unique identifier.
  • name (string) - Scope or control name.
  • scopeName (string) - Associated scope name (for assignments).
  • controlType (string) - e.g., scopeAssignment.
  • pathIds / pathNames (arrays) - Hierarchical paths.
  • owner (string) - User ID.
  • createdOn / updatedOn (ISO-8601 timestamp).

Notes and Tips

  • Start with creating scopes via the Scopes API before assignments; use parentId for hierarchies [3].
  • Scope assignments create derived "scopeAssignment" controls automatically—avoid direct creation of these via Controls API [1].
  • For bulk operations, prefer array-based requests to minimize API calls [2].
  • When expanding scopes in Controls API, use expandScopes=true to fetch nested assignments efficiently.
  • Custom fields on assignments inherit from parents unless set to "Independent" behavior—check UI for config before API use [10].
  • Monitor rate limits; hierarchical trees can be large—filter with onlyActive [3].
  • To remove assignments, re-POST without the scope ID or archive the scope.
Previous page
Next page
® 2026 Hyperproof All Rights Reserved.