API Authentication

There is one credential type: a key the merchant creates and gives you.

Getting a Key

You cannot create a key yourself. The merchant opens Argo Books, goes to Settings, then Integrations, then Argo Books API, turns it on, and clicks Create key. They name it after your app and send you the value.

Keys look like ab_ followed by 48 hex characters. The merchant sees the full value exactly once. We store only a SHA-256 fingerprint, so if they lose it nobody can recover it, and they simply revoke and create another.

Ask for your own key rather than sharing one. The merchant can then switch your app off without breaking everything else they have connected.

Sending It

Either header works:

Either header 
Authorization: Bearer ab_...
X-Api-Key: ab_...

Scopes

A key carries read, write, or both.

  • read covers every GET.
  • write covers POST and DELETE.

A request outside your scopes returns 403 insufficient_scope. If your integration only reports on data, ask for a read-only key; a merchant is far more likely to say yes.

Revocation

The merchant can revoke a key at any moment from the same screen. It stops working on the next request, which returns 401 api_key_revoked. Handle that as a permanent failure and tell your user to reconnect, rather than retrying.

There Is No Test Mode

This is a deliberate difference from most payment APIs, and worth explaining so you do not go looking for a sandbox key that does not exist.

Test credentials exist when an API hands out keys before anyone has an account, or when it simulates something external you cannot safely poke in production. Neither applies here. The account holder issues the key, and nothing you send reaches anyone's books without them approving it by hand.

If you want somewhere safe to build against, create your own Argo Books company. It is free, it is completely isolated, and it behaves identically to a real one. That is a better sandbox than a flag on a key.

Keeping the Key Safe

  • Server-side only. The API answers no CORS preflight precisely so a key cannot end up in browser JavaScript.
  • Do not commit it. The ab_ prefix exists so automated secret scanners recognise one that leaks into a public repository.
  • Do not log it. Log the Request-Id from the response instead; it identifies the request without exposing the credential.
  • If a key is ever exposed, ask the merchant to revoke it. Rotation is a 10 second job for them.
Esc