{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Troubleshooting Empty Responses","description":"Hyperproof developer resources for custom integrations.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"troubleshooting-empty-responses","__idx":0},"children":["Troubleshooting Empty Responses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide helps you diagnose cases where a GET request succeeds with 200 OK but the response body is an empty array (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]},") when retrieving objects (e.g., vendors, controls, risks, tasks) via the Hyperproof API."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"who-this-is-for","__idx":1},"children":["Who this is for"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Integrators using service accounts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Developers calling object collection endpoints such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/vendors"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/controls"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/risks"]},", etc."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-symptom","__idx":2},"children":["Common symptom"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response (200 + empty body):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"get_hyperproof_objects\": {\n    \"body\": [],\n    \"status\": 200\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A 200 indicates the request was valid and authorized, but no objects were returned. The most common reason is insufficient role or object‑level permissions for the principal (often a service account), even if the OAuth scope appears correct."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-this-happens","__idx":3},"children":["Why this happens"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Even with a valid service account and an OAuth client including the correct read scope (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendor.read"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["control.read"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["risk.read"]},"), the API may return an empty array if:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The principal lacks a suitable role (e.g., not an API Admin) and"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The principal does not appear on the object register’s explicit access list (often called the facepile) for that object type."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Hyperproof, some object types (e.g., vendors) require explicit access in addition to scopes. This behavior is intentional and protects object-level data."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-by-step-resolution","__idx":4},"children":["Step-by-step resolution"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"confirm-role-assignment","__idx":5},"children":["Confirm role assignment"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check whether the service account has a role that confers the needed visibility (e.g., API Admin)."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If not, either:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Assign the API Admin role to the service account, or"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add the service account to the object register access list (facepile) for the relevant object type(s) in the UI."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example (assign role via API):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/organizations/:orgId/users/roles\nContent-Type: application/json\n\n{\n  \"roleId\": \"<API_ADMIN_ROLE_ID>\",\n  \"principalId\": \"<SERVICE_ACCOUNT_ID>\",\n  \"principalType\": \"User\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use least privilege when possible: prefer targeted access list membership if full admin is not required."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verify-oauth-scopes","__idx":6},"children":["Verify OAuth scope(s)"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ensure the OAuth client includes the read scope for the target object type:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Vendors → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendor.read"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Controls → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["control.read"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Risks → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["risk.read"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["(and so on for other objects)"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quick scope check (example vendors):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request GET \\\n  --url \"https://api.hyperproof.app/v1/vendors\" \\\n  --header \"Authorization: Bearer $ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the token lacks the necessary scope, the response may be empty or otherwise constrained."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reauthenticate-after-permissions-change","__idx":7},"children":["Re‑authenticate after permissions change"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After changing roles or access lists, mint a new access token and retry the request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Permission changes do not retroactively affect existing tokens."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Mint a fresh token (method depends on your OAuth flow)\n# Then retry\ncurl --request GET \\\n  --url \"https://api.hyperproof.app/v1/vendors\" \\\n  --header \"Authorization: Bearer $NEW_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-data-existence-and-filters","__idx":8},"children":["Check data existence and filters"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm that objects actually exist under the organization in question."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review any query parameters (filters, pagination) that could narrow the result set to zero."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Examples:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# No filters: list all vendors visible to the principal\ncurl -sS -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  \"https://api.hyperproof.app/v1/vendors\"\n\n# Controls example with a filter that might be too restrictive\ncurl -sS -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  \"https://api.hyperproof.app/v1/controls?status=archived\"\n\n# Try removing or adjusting filters if you get []\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validate-organization--environment","__idx":9},"children":["Validate organization / environment"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Double‑check you are calling the intended tenant/org and environment (e.g., production vs. staging). A valid token for a different org with no data will yield ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"objectlevel-access-facepile","__idx":10},"children":["Object‑level access (facepile)"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For object types that enforce explicit access (e.g., vendors), add the service account to the register’s access list in the UI if you choose not to grant a broad admin role."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After updating access, re‑authenticate (Step 3)."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-diagnostic-checklist","__idx":11},"children":["Quick diagnostic checklist"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Token minted after the latest permission changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," OAuth client includes the correct read scope for the object type"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Service account has a suitable role ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["or"]}," appears on the object access list (facepile)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," You are querying the correct org/environment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Request does not include overly restrictive filters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," There are objects to return"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"expected-behavior-after-resolution","__idx":12},"children":["Expected behavior after resolution"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the principal has:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Appropriate role or explicit object access, and"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The necessary read scope(s),"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["collection endpoints will return the visible objects instead of an empty array."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Examples:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Vendors\ncurl -sS -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  \"https://api.hyperproof.app/v1/vendors\"\n\n# Controls\ncurl -sS -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  \"https://api.hyperproof.app/v1/controls\"\n\n# Risks\ncurl -sS -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  \"https://api.hyperproof.app/v1/risks\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notes","__idx":13},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Scopes control what a token is allowed to do; roles and access lists control what a principal is allowed to see. You typically need both."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prefer least privilege: grant narrow, explicit access where possible."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some endpoints (e.g., metadata or helpers) may behave differently; consult the official developer portal for details on each object API."]}]}]},"headings":[{"value":"Troubleshooting Empty Responses","id":"troubleshooting-empty-responses","depth":1},{"value":"Who this is for","id":"who-this-is-for","depth":2},{"value":"Common symptom","id":"common-symptom","depth":2},{"value":"Why this happens","id":"why-this-happens","depth":2},{"value":"Step-by-step resolution","id":"step-by-step-resolution","depth":2},{"value":"Confirm role assignment","id":"confirm-role-assignment","depth":3},{"value":"Verify OAuth scope(s)","id":"verify-oauth-scopes","depth":3},{"value":"Re‑authenticate after permissions change","id":"reauthenticate-after-permissions-change","depth":3},{"value":"Check data existence and filters","id":"check-data-existence-and-filters","depth":3},{"value":"Validate organization / environment","id":"validate-organization--environment","depth":3},{"value":"Object‑level access (facepile)","id":"objectlevel-access-facepile","depth":3},{"value":"Quick diagnostic checklist","id":"quick-diagnostic-checklist","depth":2},{"value":"Expected behavior after resolution","id":"expected-behavior-after-resolution","depth":2},{"value":"Notes","id":"notes","depth":2}],"frontmatter":{"seo":{"title":"Troubleshooting Empty Responses"}},"lastModified":"2026-02-26T22:35:50.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/hyperproof-api/api-006-empty-results","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}