Skip to content
Hyperproof API
/
/
Get Scopes

Scopes API (1.0)

Provides access to the scopes in Hyperproof.

Download OpenAPI description
scopes.openapi.json
scopes.openapi.yaml
Languages
Servers
Mock server
https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi
Hyperproof US
https://api.hyperproof.app/v1/scopes
Hyperproof Gov
https://api.hyperproofgov.app/v1/scopes
Hyperproof EU
https://api.hyperproof.eu/v1/scopes

Get Scopes

Request

GET /

Description

Retrieves details of all scopes within an organization, including their permissions, boundaries, and associated metadata.

Security
oauth2
curl -i -X GET \
  https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of scopes.

Bodyapplication/jsonArray [
idstring

The unique identifier for the scope within the organization

Example: "cb1a06f4-8ed9-4614-a17b-f8671194687e"
namestring

Name of the scope

Example: "Acme"
ownerstring

The unique identifier of the user who owns the scope

Example: "402f37f8-6054-4138-be1f-9b22ec08a86b"
descriptionstring

Description of the scope

Example: "The Acme Corp scope"
parentIdstring

The unique identifier for the scope's parent, or null for a top-level scope

Example: "b38f3039-eaa6-4d2a-948d-821a01c79185"
pathIdsArray of stringsread-only

The unique identifiers for the scope's parents, starting from the top-most scope

Example: ["6ff2fae7-02a8-4862-bf0c-61dbc0c33c23","cb1a06f4-8ed9-4614-a17b-f8671194687e"]
pathNamesArray of stringsread-only

Names of the scope's parents, starting from the top-most scope

Example: ["Acme-Parent","Acme"]
]
Response
application/json
[
  {
    "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
    "name": "Acme",
    "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
    "description": "The Acme Corp scope",
    "parentId": "b38f3039-eaa6-4d2a-948d-821a01c79185",
    "pathIds": [ … ],
    "pathNames": [ … ]
  }
]

Bulk Update Scopes

Request

PATCH /

Description

Updates one or more scopes within an organization, modifying their definitions, permissions, or associated metadata.

Security
oauth2
Bodyapplication/json
scopeIdsArray of stringsrequired

The unique identifiers of the scopes to patch

Example: ["cb1a06f4-8ed9-4614-a17b-f8671194687e"]
patchobject(ScopePatch)required
Example: {"id":"f7cc82f5-cd53-43b7-986a-3de2fa327965","name":"Updated Scope","owner":"23b806db-bad2-4f7a-b8d1-ac117790999b","description":"Scope description","status":"archived","customFields":[{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","textValue":"Antonio Moreno"}]}
patch.​idstringrequired

The unique identifier for the scope within the organization

Example: "f7cc82f5-cd53-43b7-986a-3de2fa327965"
patch.​namestring

The name of the scope

Example: "Updated Scope"
patch.​ownerstring

The unique identifier of the user who owns the scope

Example: "23b806db-bad2-4f7a-b8d1-ac117790999b"
patch.​descriptionstring

The description of the scope

Example: "Scope description"
patch.​statusstring

The status of the scope within the organization

Enum"active""archived"
Example: "archived"
patch.​customFieldsArray of objects(CustomFieldObjectValuePatch)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","textValue":"Antonio Moreno"}]
curl -i -X PATCH \
  https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scopeIds": [
      "cb1a06f4-8ed9-4614-a17b-f8671194687e"
    ],
    "patch": {
      "name": "Acme",
      "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
      "description": "The Acme Corp scope"
    }
  }'

Responses

The list of updated scopes.

Bodyapplication/jsonArray [
idstring

The unique identifier for the scope within the organization

Example: "cb1a06f4-8ed9-4614-a17b-f8671194687e"
namestring

Name of the scope

Example: "Acme"
ownerstring

The unique identifier of the user who owns the scope

Example: "402f37f8-6054-4138-be1f-9b22ec08a86b"
descriptionstring

Description of the scope

Example: "The Acme Corp scope"
parentIdstring

The unique identifier for the scope's parent, or null for a top-level scope

Example: "b38f3039-eaa6-4d2a-948d-821a01c79185"
pathIdsArray of stringsread-only

The unique identifiers for the scope's parents, starting from the top-most scope

Example: ["6ff2fae7-02a8-4862-bf0c-61dbc0c33c23","cb1a06f4-8ed9-4614-a17b-f8671194687e"]
pathNamesArray of stringsread-only

Names of the scope's parents, starting from the top-most scope

Example: ["Acme-Parent","Acme"]
]
Response
application/json
[
  {
    "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
    "name": "Acme",
    "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
    "description": "The Acme Corp scope",
    "parentId": "b38f3039-eaa6-4d2a-948d-821a01c79185",
    "pathIds": [ … ],
    "pathNames": [ … ]
  }
]

Create Scope

Request

POST /

Description

Creates a new scope within an organization, defining its permissions, boundaries, and associated metadata.

Security
oauth2
Bodyapplication/json
namestringrequired

The name of the scope

Example: "New Scope"
ownerstringrequired

The unique identifier of the user who owns the scope

Example: "23b806db-bad2-4f7a-b8d1-ac117790999b"
parentIdstring

The optional unique identifier of the scope for this scope's parent in a hierarchy of scopes

Example: "b7c74ee5-7c13-41a3-9395-d789a13cb249"
descriptionstring

The description of the scope

Example: "A newly created scope"
customFieldsArray of objects(CustomFieldObjectValuePatch)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","textValue":"Antonio Moreno"}]
curl -i -X POST \
  https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "New Scope",
    "owner": "23b806db-bad2-4f7a-b8d1-ac117790999b",
    "parentId": "b7c74ee5-7c13-41a3-9395-d789a13cb249",
    "description": "A newly created scope",
    "customFields": [
      {
        "fieldId": "ceb912ab-519b-11ee-a644-522476618ae8",
        "textValue": "Antonio Moreno"
      }
    ]
  }'

Responses

The newly created scope.

Bodyapplication/json
idstring

The unique identifier for the scope within the organization

Example: "cb1a06f4-8ed9-4614-a17b-f8671194687e"
namestring

Name of the scope

Example: "Acme"
ownerstring

The unique identifier of the user who owns the scope

Example: "402f37f8-6054-4138-be1f-9b22ec08a86b"
descriptionstring

Description of the scope

Example: "The Acme Corp scope"
parentIdstring

The unique identifier for the scope's parent, or null for a top-level scope

Example: "b38f3039-eaa6-4d2a-948d-821a01c79185"
pathIdsArray of stringsread-only

The unique identifiers for the scope's parents, starting from the top-most scope

Example: ["6ff2fae7-02a8-4862-bf0c-61dbc0c33c23","cb1a06f4-8ed9-4614-a17b-f8671194687e"]
pathNamesArray of stringsread-only

Names of the scope's parents, starting from the top-most scope

Example: ["Acme-Parent","Acme"]
Response
application/json
{
  "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
  "name": "Acme",
  "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
  "description": "The Acme Corp scope",
  "parentId": "b38f3039-eaa6-4d2a-948d-821a01c79185",
  "pathIds": [
    "6ff2fae7-02a8-4862-bf0c-61dbc0c33c23",
    "cb1a06f4-8ed9-4614-a17b-f8671194687e"
  ],
  "pathNames": [
    "Acme-Parent",
    "Acme"
  ]
}

Filter Scopes

Request

POST /filter

Description

Retrieves a set of scopes that match the specified filter criteria, returning their definitions, permissions, and related metadata.

Security
oauth2
Bodyapplication/json
programIdsArray of stringsrequired
Example: ["e8e2a5b6-767d-4345-86b9-a9d12a5836ee"]
curl -i -X POST \
  https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi/filter \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "programIds": [
      "e8e2a5b6-767d-4345-86b9-a9d12a5836ee"
    ]
  }'

Responses

The list of scopes matching the filter.

Bodyapplication/jsonArray [
idstring

The unique identifier for the scope within the organization

Example: "cb1a06f4-8ed9-4614-a17b-f8671194687e"
namestring

Name of the scope

Example: "Acme"
ownerstring

The unique identifier of the user who owns the scope

Example: "402f37f8-6054-4138-be1f-9b22ec08a86b"
descriptionstring

Description of the scope

Example: "The Acme Corp scope"
parentIdstring

The unique identifier for the scope's parent, or null for a top-level scope

Example: "b38f3039-eaa6-4d2a-948d-821a01c79185"
pathIdsArray of stringsread-only

The unique identifiers for the scope's parents, starting from the top-most scope

Example: ["6ff2fae7-02a8-4862-bf0c-61dbc0c33c23","cb1a06f4-8ed9-4614-a17b-f8671194687e"]
pathNamesArray of stringsread-only

Names of the scope's parents, starting from the top-most scope

Example: ["Acme-Parent","Acme"]
]
Response
application/json
[
  {
    "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
    "name": "Acme",
    "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
    "description": "The Acme Corp scope",
    "parentId": "b38f3039-eaa6-4d2a-948d-821a01c79185",
    "pathIds": [ … ],
    "pathNames": [ … ]
  }
]

Get Scope

Request

GET /{scopeId}

Description

Retrieves details of a specific scope by its unique ID, including its permissions, boundaries, and associated metadata.

Security
oauth2
Path
scopeIdstringrequired

Unique identifier of the scope.

curl -i -X GET \
  'https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi/{scopeId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The scope with the specified identifier.

Bodyapplication/json
idstring

The unique identifier for the scope within the organization

Example: "cb1a06f4-8ed9-4614-a17b-f8671194687e"
namestring

Name of the scope

Example: "Acme"
ownerstring

The unique identifier of the user who owns the scope

Example: "402f37f8-6054-4138-be1f-9b22ec08a86b"
descriptionstring

Description of the scope

Example: "The Acme Corp scope"
parentIdstring

The unique identifier for the scope's parent, or null for a top-level scope

Example: "b38f3039-eaa6-4d2a-948d-821a01c79185"
pathIdsArray of stringsread-only

The unique identifiers for the scope's parents, starting from the top-most scope

Example: ["6ff2fae7-02a8-4862-bf0c-61dbc0c33c23","cb1a06f4-8ed9-4614-a17b-f8671194687e"]
pathNamesArray of stringsread-only

Names of the scope's parents, starting from the top-most scope

Example: ["Acme-Parent","Acme"]
Response
application/json
{
  "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
  "name": "Acme",
  "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
  "description": "The Acme Corp scope",
  "parentId": "b38f3039-eaa6-4d2a-948d-821a01c79185",
  "pathIds": [
    "6ff2fae7-02a8-4862-bf0c-61dbc0c33c23",
    "cb1a06f4-8ed9-4614-a17b-f8671194687e"
  ],
  "pathNames": [
    "Acme-Parent",
    "Acme"
  ]
}

Update Scope

Request

PATCH /{scopeId}

Description

Updates an existing scope with new values, modifying its permissions, boundaries, or other defined attributes.

Security
oauth2
Path
scopeIdstringrequired

Unique identifier of the scope to update.

Bodyapplication/json
idstringrequired

The unique identifier for the scope within the organization

Example: "f7cc82f5-cd53-43b7-986a-3de2fa327965"
namestring

The name of the scope

Example: "Updated Scope"
ownerstring

The unique identifier of the user who owns the scope

Example: "23b806db-bad2-4f7a-b8d1-ac117790999b"
descriptionstring

The description of the scope

Example: "Scope description"
statusstring

The status of the scope within the organization

Enum"active""archived"
Example: "archived"
customFieldsArray of objects(CustomFieldObjectValuePatch)
Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","textValue":"Antonio Moreno"}]
curl -i -X PATCH \
  'https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi/{scopeId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "f7cc82f5-cd53-43b7-986a-3de2fa327965",
    "name": "Updated Scope",
    "owner": "23b806db-bad2-4f7a-b8d1-ac117790999b",
    "description": "Scope description",
    "status": "archived",
    "customFields": [
      {
        "fieldId": "ceb912ab-519b-11ee-a644-522476618ae8",
        "textValue": "Antonio Moreno"
      }
    ]
  }'

Responses

The updated scope.

Bodyapplication/json
idstring

The unique identifier for the scope within the organization

Example: "cb1a06f4-8ed9-4614-a17b-f8671194687e"
namestring

Name of the scope

Example: "Acme"
ownerstring

The unique identifier of the user who owns the scope

Example: "402f37f8-6054-4138-be1f-9b22ec08a86b"
descriptionstring

Description of the scope

Example: "The Acme Corp scope"
parentIdstring

The unique identifier for the scope's parent, or null for a top-level scope

Example: "b38f3039-eaa6-4d2a-948d-821a01c79185"
pathIdsArray of stringsread-only

The unique identifiers for the scope's parents, starting from the top-most scope

Example: ["6ff2fae7-02a8-4862-bf0c-61dbc0c33c23","cb1a06f4-8ed9-4614-a17b-f8671194687e"]
pathNamesArray of stringsread-only

Names of the scope's parents, starting from the top-most scope

Example: ["Acme-Parent","Acme"]
Response
application/json
{
  "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
  "name": "Acme",
  "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
  "description": "The Acme Corp scope",
  "parentId": "b38f3039-eaa6-4d2a-948d-821a01c79185",
  "pathIds": [
    "6ff2fae7-02a8-4862-bf0c-61dbc0c33c23",
    "cb1a06f4-8ed9-4614-a17b-f8671194687e"
  ],
  "pathNames": [
    "Acme-Parent",
    "Acme"
  ]
}

Get Scope Tree

Request

GET /tree

Description

Retrieves the full scope tree, returning the hierarchical structure of scopes and their relationships within the organization.

Security
oauth2
Bodyapplication/json
onlyActiveboolean

Whether or not to exclude archived scopes in the results

Example: true
curl -i -X POST \
  https://developer.hyperproof.app/_mock/hyperproof-api/scopes/scopes.openapi/tree \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "onlyActive": true
  }'

Responses

The newly created scope.

Bodyapplication/json
scopeobject(Scope)
Example: {"id":"cb1a06f4-8ed9-4614-a17b-f8671194687e","name":"Acme","owner":"402f37f8-6054-4138-be1f-9b22ec08a86b","description":"The Acme Corp scope","parentId":"b38f3039-eaa6-4d2a-948d-821a01c79185","pathIds":["6ff2fae7-02a8-4862-bf0c-61dbc0c33c23","cb1a06f4-8ed9-4614-a17b-f8671194687e"],"pathNames":["Acme-Parent","Acme"]}
childrenArray of objects(Scope)
Example: [{"id":"71f5fba2-bd08-4e7e-9e6c-05209956f22d","name":"Acme-Child","owner":"402f37f8-6054-4138-be1f-9b22ec08a86b","description":"A child scope of Acme","parentId":"cb1a06f4-8ed9-4614-a17b-f8671194687e","pathIds":["cb1a06f4-8ed9-4614-a17b-f8671194687e","71f5fba2-bd08-4e7e-9e6c-05209956f22d"],"pathNames":["Acme","Acme-Child"]}]
Response
application/json
{
  "scope": {
    "id": "cb1a06f4-8ed9-4614-a17b-f8671194687e",
    "name": "Acme",
    "owner": "402f37f8-6054-4138-be1f-9b22ec08a86b",
    "description": "The Acme Corp scope",
    "parentId": "b38f3039-eaa6-4d2a-948d-821a01c79185",
    "pathIds": [ … ],
    "pathNames": [ … ]
  },
  "children": [
    { … }
  ]
}
® 2026 Hyperproof All Rights Reserved.