{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Keys and scopes","description":"Read US healthcare contracts and organizations, and work with your saved work, from your own code.","siteUrl":"https://docs.hrcledger.com","llmstxt":{"title":"HRC Ledger API","description":"One key, one envelope, every route and guide."}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"keys-and-scopes","__idx":0},"children":["Keys and scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An API key is how your code signs in. You make keys on the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://hrcledger.com/settings/api-keys"},"children":["key page"]}," in the app. Each key has a name"," ","and a set of scopes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the key in one header on every call:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Authorization: Bearer hck_live_...\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scopes","__idx":1},"children":["Scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A scope says what a key may do. Pick scopes when you make the key. A call that"," ","needs a scope the key does not have gets a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," with the code"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insufficient_scope"]},", and the missing scope in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.scope"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read scopes only look. Write scopes change your saved work, or spend the key's"," ","daily allowance. Approve scopes say yes to work that is waiting for review."]},{"$$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":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Kind"},"children":["Kind"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it lets a key do"},"children":["What it lets a key do"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Ticked for you"},"children":["Ticked for you"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contracts:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search and read contracts."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["market:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search and read organizations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent:ask"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask the assistant questions, using the key's daily allowance."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lists:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read your Lists and their rows, and download them."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lists:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Make, rename and archive Lists, and add or remove rows."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actions:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read your plans and the steps you own."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actions:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Make, change and archive plans, and mark steps done."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drafts:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read your drafts, including the approved ones."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drafts:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write, change and archive drafts."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drafts:approve"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Approve"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Approve a draft that is waiting for review."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actions:approve"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Approve"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Approve a plan that is waiting for review."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversations:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read your conversations with the assistant."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conversations:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rename and delete conversations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["memory:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read what HRC Ledger knows about your company."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data:query"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Run read-only questions straight against the data."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-a-key-never-does","__idx":2},"children":["What a key never does"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A key never decides what the HRC Ledger assistant proposes. Only a person in the"," ","app can say yes or no to the assistant's changes. A key that tries gets a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No list or read route returns a person's email or phone. An ask answer can, the"," ","same way it does in the app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A key cannot claim a plan. The server ignores one sent in a call."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-much-a-key-can-do","__idx":3},"children":["How much a key can do"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each key has its own limits:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["60 calls a minute."]}," Call 61 in the same minute gets a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," with a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header. Wait that many seconds and try again."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["200 asks a day."]}," Ask 201 gets a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," that says the limit and how many seconds"," ","until it resets."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reads are free within these limits. Each ask uses one of the key's 200 for the day."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An account can hold ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20 live keys"]}," at once. A revoked key does not count."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"revoke-a-key","__idx":4},"children":["Revoke a key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Press ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Revoke"]}," next to the key on the key page. It stops working at once and"," ","cannot be turned back on. Make a new key if you need one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Revoke a key right away if it was shared by mistake. You cannot see a key again"," ","after you make it, so a lost key is replaced, not found."]}]},"headings":[{"value":"Keys and scopes","id":"keys-and-scopes","depth":1},{"value":"Scopes","id":"scopes","depth":2},{"value":"What a key never does","id":"what-a-key-never-does","depth":2},{"value":"How much a key can do","id":"how-much-a-key-can-do","depth":2},{"value":"Revoke a key","id":"revoke-a-key","depth":2}],"frontmatter":{"seo":{"title":"Keys and scopes"}},"lastModified":"2026-10-22T07:39:08.493Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer/keys-and-scopes","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}