Skip to content
Developers
Svenska GitHub

Guides

Scopes

Every app and API key has a list of scopes. They are the same permissions NONOX's roles use, so a bookkeeper and an app with vouchers:post post in the same way, with the same checks.

Every scope

The table is generated from the OpenAPI file. The endpoints in the right-hand column need the scope.

ScopeGrantsEndpoints
vouchers:view Read vouchers, attachments, chart of accounts, fiscal years and periods, cost centres, projects, voucher series and VAT codes GET /accounts GET /accounts/{number} GET /vat-codes GET /fiscal-years GET /fiscal-years/{fiscalYear} GET /fiscal-years/{fiscalYear}/periods GET /cost-centers GET /cost-centers/{costCenter} GET /projects GET /projects/{project} GET /voucher-series GET /vouchers GET /vouchers/{voucher} GET /vouchers/{voucher}/attachments GET /vouchers/{voucher}/attachments/{attachment}/content
vouchers:create Create and change voucher drafts and add attachments POST /vouchers PATCH /vouchers/{voucher} DELETE /vouchers/{voucher} POST /vouchers/{voucher}/attachments POST /invoices/{invoice}/issue POST /invoices/{invoice}/payments POST /supplier-invoices/{supplierInvoice}/register POST /supplier-invoices/{supplierInvoice}/payments
vouchers:post Post vouchers (irreversible; only a correction can undo the effect) POST /vouchers/{voucher}/post POST /invoices/{invoice}/issue POST /invoices/{invoice}/payments POST /supplier-invoices/{supplierInvoice}/register POST /supplier-invoices/{supplierInvoice}/payments
vouchers:correct Correct posted vouchers with a correcting voucher POST /vouchers/{voucher}/correct
accounts:manage Create and change cost centres and projects POST /cost-centers PATCH /cost-centers/{costCenter} POST /projects PATCH /projects/{project}
reports:view Read the trial balance, general ledger, balance sheet and income statement GET /reports/trial-balance GET /reports/general-ledger GET /reports/balance-sheet GET /reports/income-statement
vat:prepare Read the VAT return per period GET /vat-periods GET /vat-return
export:sie Download the bookkeeping as a SIE 4 file GET /fiscal-years/{fiscalYear}/sie
invoices:view Read customers, articles, customer invoices and incoming payments GET /customers GET /customers/{customer} GET /articles GET /articles/{article} GET /invoices GET /invoices/{invoice} GET /invoices/{invoice}/pdf GET /payments
invoices:create Create and change customers, articles and draft customer invoices POST /customers PATCH /customers/{customer} POST /articles PATCH /articles/{article} POST /invoices PATCH /invoices/{invoice}
invoices:send Issue customer invoices (with vouchers:create and vouchers:post) and e-mail them POST /invoices/{invoice}/issue POST /invoices/{invoice}/send
invoices:credit Credit unpaid customer invoices POST /invoices/{invoice}/credit
payments:create Register incoming payments and supplier payments (with vouchers:create and vouchers:post) POST /invoices/{invoice}/payments GET /supplier-invoices GET /supplier-invoices/{supplierInvoice} POST /supplier-invoices/{supplierInvoice}/payments GET /supplier-payments
supplier-invoices:create Read suppliers and supplier invoices, create suppliers and draft and register supplier invoices GET /suppliers POST /suppliers GET /suppliers/{supplier} PATCH /suppliers/{supplier} GET /supplier-invoices POST /supplier-invoices GET /supplier-invoices/{supplierInvoice} PATCH /supplier-invoices/{supplierInvoice} DELETE /supplier-invoices/{supplierInvoice} POST /supplier-invoices/{supplierInvoice}/file POST /supplier-invoices/{supplierInvoice}/register GET /supplier-payments
supplier-invoices:approve Read and approve supplier invoices (never ones the same person registered, while the company requires separate approval) GET /suppliers GET /suppliers/{supplier} GET /supplier-invoices GET /supplier-invoices/{supplierInvoice} POST /supplier-invoices/{supplierInvoice}/approve GET /supplier-payments

GET /company needs no particular scope: every valid key or token may see which company it belongs to.

What a call may actually do

A call may do what both the key's or app's scopes and the person behind it allow, at that moment:

The person's role today The key's scopes May the key post?
Bookkeeper vouchers:view, vouchers:post Yes
Approver (may not post) vouchers:view, vouchers:post No, 403 insufficient_scope
Bookkeeper vouchers:view No, 403 insufficient_scope
Has left the company vouchers:post No, 401

The intersection is checked on every call, in every check in the system, not only for the scope the route names. A changed role therefore counts from the next call, without the app doing anything.

When a scope is missing

JSON
{
  "type": "urn:nonox:problem:insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Nyckeln eller appen saknar behörigheten vouchers:post, eller så har personen som gav den inte längre den behörigheten i företaget.",
  "instance": "urn:nonox:request:7f3c2a9e-4b1d-4c8e-9a51-2d6f0e8b3c17",
  "required_scopes": ["vouchers:post"]
}

required_scopes says what is needed. For an OAuth app it means the person has to approve the app again with more scopes; for an API key, that a new key has to be created.

Ask for as little as possible

Ask only for the scopes the app actually uses. The person sees the list in Swedish when approving, and a short list is easier to say yes to. vouchers:post cannot be undone in the books (only corrected), so ask for it only when the app really posts.

Things the API never does

  • Return personal identity numbers. A customer has has_personal_number; the number itself can be written but never read.
  • Change or delete a posted voucher. It can only be corrected.
  • Give access to payroll, payslips or the staff ledger. There are no scopes for them.

Suggest a change on GitHub