{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Understanding Service Account Credentials and the hp-proof-owned-by Field","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":"understanding-service-account-credentials-and-the-hp-proof-owned-by-field","__idx":0},"children":["Understanding Service Account Credentials and the hp-proof-owned-by Field"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When interacting with the Hyperproof API, proof objects must always be owned by a real human user in the organization. This article explains the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hp-proof-owned-by"]}," field, why it exists, and when you must use it — particularly when authenticating with service account credentials."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"personal-api-credentials-vs-service-account-credentials","__idx":2},"children":["Personal API Credentials vs. Service Account Credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hyperproof supports two types of API clients, each with distinct security and ownership implications:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"personal-api-client","__idx":3},"children":["Personal API Client"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Inherits your roles and permissions in the organization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Objects created or updated via the API are attributed to you (the human user)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hp-proof-owned-by"]}," field is optional — if omitted, you are automatically set as the proof owner."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The client is private to you; no other user or admin can see it."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"service-account-api-client","__idx":4},"children":["Service Account API Client"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Operates as a distinct, non-human service identity with an assigned organization role."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Visible to all administrators in the organization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Service accounts cannot be owners or assignees on Hyperproof objects."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hp-proof-owned-by"]}," field is required when uploading proof — omitting it results in a 400 Bad Request with the message: \"Service accounts cannot be proof owners.\""]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-does-this-restriction-exist","__idx":5},"children":["Why Does This Restriction Exist?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For accountability and traceability, Hyperproof enforces that every object (proof, policy, etc.) is owned by a real user. This has several downstream consequences:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Facepiles and UI attribution"]}," — The Hyperproof UI displays owner avatars (facepiles) on proof items, controls, and tasks. These must resolve to a real user. When a service account uploads proof with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hp-proof-owned-by"]}," set, the UI shows the designated user as the owner and the service account name in the \"Uploaded By\" column."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Audit trail integrity"]}," — The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdBy"]}," field records who performed the action (the service account), while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ownedBy"]}," records who is responsible for the proof. This separation preserves a clear chain of custody."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Object lifecycle"]}," — Owners can be notified, assigned follow-up tasks, and are visible in compliance reporting. A non-human identity cannot fulfill these responsibilities."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This same restriction applies to other object types — e.g., service accounts cannot be policy owners either."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-hp-proof-owned-by-field","__idx":6},"children":["The hp-proof-owned-by Field"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detail"},"children":["Detail"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hp-proof-owned-by"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Passed as"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Multipart form-data field"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Value"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID of an active Hyperproof user"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required when"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticating with a service account token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional when"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticating with a personal API client token"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The target user must be an active user in the organization — inactive or deprovisioned users cannot be assigned as proof owners."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrieving-user-uuids","__idx":7},"children":["Retrieving User UUIDs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the Get Organization Users endpoint to retrieve a list of users and their UUIDs:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --silent \\\n  --header \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  \"https://api.hyperproof.app/v1/users\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-uploading-proof-with-a-service-account","__idx":8},"children":["Example: Uploading Proof with a Service Account"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# 1. Obtain a token using client credentials flow\nACCESS_TOKEN=$(curl -s -d \\\n  \"grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET\" \\\n  https://accounts.hyperproof.app/oauth/token | jq -r '.access_token')\n\n# 2. Upload proof with explicit owner (REQUIRED for service accounts)\ncurl --request POST \\\n  --url https://api.hyperproof.app/v1/proof \\\n  --header \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  --form proof=@\"./evidence/SOC2_Report.pdf\" \\\n  --form hp-proof-owned-by=\"$USER_UUID\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-uploading-proof-linked-to-a-control","__idx":9},"children":["Example: Uploading Proof Linked to a Control"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \\\n  --url \"https://api.hyperproof.app/v1/controls/$CONTROL_ID/proof\" \\\n  --header \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  --form proof=@\"./evidence/PrivacyPolicy.pdf\" \\\n  --form hp-proof-owned-by=\"$USER_UUID\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-comparison-summary","__idx":10},"children":["Security Comparison Summary"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Concern"},"children":["Concern"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Personal API Client"},"children":["Personal API Client"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Service Account API Client"},"children":["Service Account API Client"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Visibility"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Private to the creator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Visible to all org admins"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Permissions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inherits your user roles"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Has its own assigned role"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Proof ownership"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Automatic (you)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Must specify via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hp-proof-owned-by"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdBy"]}," attribution"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your user ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Service account ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UI facepile / owner display"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your avatar"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Designated user's avatar"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blast radius if compromised"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Limited to your permissions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Potentially broader; shared credential"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-errors","__idx":11},"children":["Common Errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Service accounts cannot be proof owners.\" (400)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hp-proof-owned-by"]}," omitted or set to the service account's own ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provide a valid human user UUID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400 on owner validation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User UUID is inactive or invalid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the Users API to retrieve an active user's UUID"]}]}]}]}]}]},"headings":[{"value":"Understanding Service Account Credentials and the hp-proof-owned-by Field","id":"understanding-service-account-credentials-and-the-hp-proof-owned-by-field","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Personal API Credentials vs. Service Account Credentials","id":"personal-api-credentials-vs-service-account-credentials","depth":2},{"value":"Personal API Client","id":"personal-api-client","depth":3},{"value":"Service Account API Client","id":"service-account-api-client","depth":3},{"value":"Why Does This Restriction Exist?","id":"why-does-this-restriction-exist","depth":2},{"value":"The hp-proof-owned-by Field","id":"the-hp-proof-owned-by-field","depth":2},{"value":"Retrieving User UUIDs","id":"retrieving-user-uuids","depth":2},{"value":"Example: Uploading Proof with a Service Account","id":"example-uploading-proof-with-a-service-account","depth":2},{"value":"Example: Uploading Proof Linked to a Control","id":"example-uploading-proof-linked-to-a-control","depth":2},{"value":"Security Comparison Summary","id":"security-comparison-summary","depth":2},{"value":"Common Errors","id":"common-errors","depth":2}],"frontmatter":{"seo":{"title":"Understanding Service Account Credentials and the hp-proof-owned-by Field"}},"lastModified":"2026-05-19T20:32:54.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/hyperproof-api/api-010-service-account-credentials","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}