Authentication
One header on every call. Making a key takes about a minute, and what it can touch is decided when you make it.
Making one
In ObraLedger, open Settings, then API keys, and create one. You pick the company it acts on and the parts of the product it can touch.
We show the key once. After that we keep only a hash of it, so nobody can read it back to you later - and that includes us. Put it somewhere safe as you make it. If you lose it, make another and delete the old one; there's no recovering the first.
Using it
One header, on every call, including the ones that fail.
curl https://app.obraledger.com/api/public/v1/contacts \
-H "X-AUTH-TOKEN: obl_live_..."What a key can't do
Two limits, and neither can be widened from inside the key.
- It works on one company. If you run two sets of books here, that's two keys. A key can't reach across.
- It can never do more than the person who made it. If your own account can't see purchase orders, a key you create can't either. Ticking more boxes on the key won't change that - the permission has to exist on the person first.
That second one is why forbidden and scope_required are different failures. One means the key wasn't issued for this; the other means nobody could have issued it, because the permission isn't there to give.
Scopes
A key carries the specific things it may do, named after the part of the product and the action:
CONTACT.VIEW to read contacts,
PRODUCT.MODIFY to change a product,
and so on. Give a key only what the job needs. A connector that reads your catalog for a storefront
has no business being able to delete it.
If a key gets out
Delete it in Settings, then API keys. It stops working immediately, and calls using it come back as unauthenticated. Then make a new one and put it wherever the old one lived.
Keys belong in your server's configuration, not in anything you ship to a browser or commit to a repository. A key in front-end code is readable by everybody who loads the page.
Next
- How the API behaves - paging, changes, money, retries.
- Try a call with the key you just made.
Building something and stuck? Tell us - we'd rather hear it than have you guess.