The REST API: Tokens, Permissions and Limits
There are two APIs behind the product: a published Developer API with keys you issue in Settings, which reads your records and writes their master data, and the much larger API the mobile app runs on. Which one to build on, how each authenticates, and what each is genuinely good for.
Most SME operations platforms answer "do you have an API?" with yes, and the yes covers everything from a documented public interface to three endpoints that exist because the mobile app needed them. Ours is closer to the second than the first in origin and closer to the first in coverage, and the honest framing is worth having before you plan a build around it.
There are two surfaces, and the difference between them is the most useful thing on this page. The Developer API is the published contract: read endpoints across inventory, sales and procurement, plus create and update for items, customers and vendors under write scopes you grant by name, authenticated by a key you issue yourself in Settings → API & Webhooks, scoped to the areas you tick, documented in the API reference and described by an OpenAPI file you can generate a client from. Behind it sits the API the mobile app uses — several hundred endpoints spanning inventory, procurement, assets, sales, POS, projects, HR, accounting and reporting, writes included, behind user tokens and the same permission model as the web interface. That second surface is real and usable, and it is not a promise: endpoints there can change between releases.
How you get a key or a token
For the Developer API, an administrator creates a key in Settings → API & Webhooks, chooses the Developer API service and ticks only the scopes the integration needs. The key carries your organization with it, so no request ever names a workspace, and it can be revoked from the same screen. That is the right door for a reporting extract, a website stock feed or a third party you hand a key to.
For anything the Developer API does not cover — transactions, stock movements, or modules outside its scopes — you use the app's own authentication endpoints: post a user's credentials and receive a bearer token. The rest of this page is mostly about that token, because it behaves differently from a key.
What the token is
Property Reality
Type Bearer token, sent as an Authorization header
Issued by The app authentication endpoints (a Developer API key comes from Settings instead)
Abilities A copy of that user's workspace permissions, plus a mobile marker
Lifetime Expires — thirty days by default
Scope One organisation. There is no cross-workspace token
The third row is the important one and it is a genuinely good design: a token cannot do more than the person it belongs to. Grant that user fewer permissions and every script using their token becomes narrower, immediately, with no code change. It also means the reverse — an integration token belonging to an administrator is an administrator.
Create a user for the integration
This follows directly from how abilities work and it is the single most useful practice on this page. Do not run a script on a person's token.
-
Create a named user for the integration
Something recognisable — "Stock feed", "Website orders". Not a shared human account, and not the administrator.
-
Give it a role with exactly the permissions the script needs
Usually read on two modules and write on one. Because the token copies these, this is where the security boundary genuinely lives.
-
Note that it will appear in the audit trail under that name
Which is the point. Six months later "who changed this item" answers "Stock feed" rather than a former employee.
-
Plan for expiry
Tokens expire. A script that has run for a month and then stops has almost certainly hit that, and it needs a re-authentication path rather than a hard-coded string.
-
Remember MFA enforcement
If your organisation requires MFA, the API respects it. Work out how your integration user satisfies that before you build, not afterwards.
The layer nobody expects
Authenticated API traffic passes through the same audit logging as the web interface, which means an integration writing a thousand records a day is a thousand audit entries a day attributed to that user. This is correct and occasionally surprising when someone opens the audit log looking for a human.
What the API is genuinely good for
Good use
A recurring extract into your own warehouse
For a one-off copy of everything, use the full organisation export on the account and danger-zone page instead — one ZIP, attachments included. The API earns its place when you want the same records pulled on a schedule into a reporting database of your own, page by page.
Good use
Feeding stock or price data to your own website
A read key, low risk, and the shape of thing the API handles well. Cache aggressively on your side; you are rate-limited and you do not need live figures on a catalogue page.
Careful
Writing transactions from another system
Possible, and it bypasses nothing — the permission model and the posting rules still apply, which is the point. But you now own idempotency: a retried request that creates a second record is your bug to find.
Wrong tool
A continuous two-way sync with another business system
There is no change feed — the updated_since filter reports records that changed, not ones that were deleted — and the outbound webhooks cover eight events rather than every record change. Building continuous sync means polling, which will hit rate limits and will drift. Do not architect around this.
The boundaries, stated
What AWRA OpsHub does today
- A published Developer API with keys issued in Settings, scoped per area, rate-limited per key, that reads inventory, sales and procurement and creates and updates items, customers and vendors under write scopes a read key never satisfies — with an Idempotency-Key on POST and every write audited against the key — documented at the API reference and described by an OpenAPI file.
- Several hundred further authenticated endpoints across inventory, procurement, assets, sales, POS, projects, HR, accounting and reporting, used by the mobile app.
- Bearer token authentication with per-token abilities copied from the user's workspace permissions.
- Rate limiting, MFA enforcement and audit logging applied to API traffic the same way as to web traffic.
- A dedicated offline sync interface with idempotency on a client-supplied operation id, built for the mobile app and genuinely robust.
- A separate authenticated surface for supplier users, so a vendor-facing integration does not need a staff account.
- A single inbound webhook endpoint for the other direction, authenticated by token and optionally HMAC-signed.
- Outbound webhooks on eight subscribable events — invoice created, invoice paid, purchase order created, customer created, vendor created, item at its reorder point, stock transfer completed, and a workflow action — signed, sent only to https addresses, and retried with a backoff that doubles.
More we can add to your workspace
- Transaction writes in the published Developer API — invoices, orders, stock movements — with the same version guarantee its reads and master-data writes carry. Those go through the app's own endpoints today, which can change between releases.
- A change feed that reports deletions, and a webhook on every record change beyond the eight events — so continuous sync is polling, which will not scale.
- A GraphQL, a bulk write endpoint, and a SQL or query workbench of any kind.
If you are planning a substantial build, talk to us first — not for approval, but because we would rather tell you which endpoints are stable than have you discover it in a release. That conversation is free, and it is what stands in for a version guarantee until one exists.
Anything above that you need, we can build for you
Everything listed above as something we can add describes what ships in the standard product today — it is a starting point, not a limit on what AWRA OpsHub can do for your organisation. Kenya's eTIMS integration and its maintained payroll engine are both in the product because clients needed them and commissioned them; neither appeared by itself, and the same door is open for whatever you just read about. One qualification so this is worth what it claims: a small number of things on this blog we deliberately leave to a specialist rather than build — a statutory ledger we will not sign our name to, a rule that would decide a tax question for you, a clinical or member-funds record that belongs in a regulated system — and where that is true the post says so in those words. Everything else is a scope, a timeline and a price.
The operational work, which is what most commissions actually are
An extra approval stage in a chain that does not match the standard one, a custom field set on employees or assets that only your sector needs, an expiry that has to block an order rather than send an email, a report your board asks for in a shape nothing produces, or a scanner or weighbridge feeding the goods-in door. These are the commissions we are asked for most often and the smallest ones we quote — and unlike a revenue-authority pipeline, none of them waits on a regulator.
The module-shaped additions, which are the ones readers ask for most often
A price list with real discount authority, a customer-facing quotation that expires, a bill of materials or recipe costing, a staff advance that is issued, acquitted and chased, a member or unit ledger, a matching rule that holds a payment. Each of these is a build rather than a setting, and each has been quoted before — a bigger piece of work than a custom field, with a written spec and a date instead of a roadmap slide.
The report, document or pack nothing currently produces
The board pack in the shape your board actually asks for, a donor or funder layout, an invoice or receipt template carrying what your regulator or your customer expects, a dataset the report builder cannot reach yet. Usually the fastest thing on this list to deliver, because the data is already in the system.
Systems, rails and hardware you already run
The accounting package, CRM, online store, core banking or custom database you intend to keep — connected through our API so a fact is entered once and appears everywhere it is needed. Plus the physical edge: a scanner, a scale, a weighbridge or a till peripheral feeding the door it belongs to.
How it works: you describe the requirement, we return a written scope, timeline and cost, and once agreed it is built into your environment and maintained as part of the product. Nothing here waits on a regulator or a published specification, which is why operational builds are the ones we quote fastest. Tell us the requirement that would otherwise rule us out — that is a better first conversation than a demo.
Tell us what your operation needsThe two other doors
Worth knowing about because they solve problems people reach for the API to solve, more cheaply. If you want an external event to cause something here, the inbound webhook is one authenticated endpoint and needs no polling. If you want something here to cause an event elsewhere, outbound webhooks and connectors fire on eight system events or on your own workflow rules, and need no code on our side at all.
Between those two and the import templates, a surprising proportion of the integrations people initially scope as API work turns out not to need a developer. Check that first — it is a cheaper answer and it stays working when your developer moves on.
Our take
Build reads and master-data writes on the Developer API: a key from Settings, narrow scopes, a documented contract. Reach for the app's own endpoints only for transactions, with a named integration user on the narrowest role and a plan for token expiry. Try an integration in a sandbox workspace before your live one. There is still no feed of deletions, so check whether a webhook or an import template solves your problem before you write code.
Talk to us before you scope the build
We will tell you which endpoints are stable, which of the four integration doors fits your problem, and where an inbound webhook would do the job without a developer — before you commit anyone's time.
See the integrationsFrequently asked questions
Is there a REST API?
Yes, two. The Developer API is the published one: read endpoints across inventory, sales and procurement, plus create and update for items, customers and vendors under write scopes, authenticated by a key you issue in Settings, documented at the API reference with an OpenAPI file. Behind it, several hundred further endpoints used by the mobile app cover the rest of the product, writes included, with rate limiting, MFA enforcement and audit logging — usable, but not promised stable across releases. To test without touching live records, an admin can open a sandbox workspace: a copy of your configuration with none of your records.
How do we get an API token?
For the Developer API, an administrator creates a key in Settings → API & Webhooks and ticks the scopes it needs; the key carries your organization and can be revoked there. For the app's own endpoints, post a user's credentials to the authentication endpoints and receive a bearer token. Those tokens expire — thirty days by default, sooner if your security policy sets a session limit — so build a re-authentication path rather than hard-coding a string.
What can a token do?
Exactly what the user it belongs to can do. Token abilities are a copy of that user's workspace permissions, so narrowing the user narrows every script using the token immediately with no code change. The corollary matters as much: a token belonging to an administrator is an administrator. Create a named integration user with the narrowest role that works.
Can we build a continuous two-way sync with another system?
Not well. There is no change feed that reports deletions, and outbound webhooks cover eight events rather than every change, so continuous sync means polling — which will hit rate limits and will drift out of step. Push-style integration works: something happens elsewhere, it posts to the inbound webhook. Pull-style continuous sync is not a shape this API supports.
Is the API a way to export all our data?
It can be, but it is no longer the route we would point you at for a one-off copy. An administrator can export the whole organisation from the account and danger-zone page — every table as a CSV and every stored attachment in one ZIP, with a checksummed manifest. The API is the better tool when you want records pulled repeatedly into a system of your own. Read writing your exit plan first for what a migration-grade extract needs to include.
Does API activity appear in the audit trail?
Yes, under the name of the user whose token was used, which is one more reason to create a dedicated integration user. An integration writing a thousand records a day produces a thousand audit entries a day attributed to that name — correct behaviour, and occasionally surprising to whoever opens the audit log expecting to find a person.
