An API key is how your code signs in. You make keys on the key page in the app. Each key has a name and a set of scopes.
Send the key in one header on every call:
Authorization: Bearer hck_live_...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 403 with the code insufficient_scope, and the missing scope in error.scope.
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.
| Scope | Kind | What it lets a key do | Ticked for you |
|---|---|---|---|
contracts:read | Read | Search and read contracts. | Yes |
market:read | Read | Search and read organizations. | Yes |
agent:ask | Write | Ask the assistant questions, using the key's daily allowance. | No |
lists:read | Read | Read your Lists and their rows, and download them. | No |
lists:write | Write | Make, rename and archive Lists, and add or remove rows. | No |
actions:read | Read | Read your plans and the steps you own. | No |
actions:write | Write | Make, change and archive plans, and mark steps done. | No |
drafts:read | Read | Read your drafts, including the approved ones. | No |
drafts:write | Write | Write, change and archive drafts. | No |
drafts:approve | Approve | Approve a draft that is waiting for review. | No |
actions:approve | Approve | Approve a plan that is waiting for review. | No |
conversations:read | Read | Read your conversations with the assistant. | No |
conversations:write | Write | Rename and delete conversations. | No |
memory:read | Read | Read what HRC Ledger knows about your company. | No |
data:query | Read | Run read-only questions straight against the data. | No |
- 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
403. - No list or read route returns a person's email or phone. An ask answer can, the same way it does in the app.
- A key cannot claim a plan. The server ignores one sent in a call.
Each key has its own limits:
- 60 calls a minute. Call 61 in the same minute gets a
429with aRetry-Afterheader. Wait that many seconds and try again. - 200 asks a day. Ask 201 gets a
429that says the limit and how many seconds until it resets.
Reads are free within these limits. Each ask uses one of the key's 200 for the day.
An account can hold 20 live keys at once. A revoked key does not count.
Press 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.
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.