Roles and permissions

Almost everyone has an ordinary account, and everything below — the four roles and what they allow — is about it. A reseller account holds no company roles: what it can do is on Reseller accounts. Reseller access on an existing account changes nothing below: you keep your companies and your roles, and gain the reseller side on top.

Tax Star staff approve every OAuth app before it can get a token, and are the only ones who create reseller accounts or switch reseller access on or off. Neither can be done by sign-up.

Creating an entity makes you its Admin. Every other role arrives by invitation from an Admin or Editor of the entity, and is held on that entity only.

An Editor does everything an Admin does day to day, seeing, inviting and removing people included, but can never change or remove an Admin, or delete the entity. That is what stops control of an entity being handed on, or taken away, by someone who was only given access to it. Approvers and Viewers do not see who else has access, or who has been invited.

The rules are checked on every request, not only on the buttons. Where your role does not allow something the control is still shown, switched off, with a note naming the role that can. The Roles & Permissions card on each entity's details page shows your own role and this table for that entity.

1. An Admin or Editor invites someone by email on the entity details page and picks a role — Editor, Approver or Viewer. An app owned by an Admin or Editor can send the same invitation with POST /oauth/entities/{entity_id}/members.
2. The invitation link is valid for 24 hours.
3. Editor or Viewer: with an account, they sign in with the invited email address, then open the link. Without one, the link opens a confirmation page and Accept & create account creates it, emailing a temporary password. The invitation is tied to that address. An account made this way can be invited to other companies like any other, but cannot create a company of its own until its holder onboards one through the FTA — see Users and roles.
4. Approver: no account needed. The link opens a confirmation page, and pressing Accept invitation is the whole step.
5. Until they accept, they are listed as invited and see nothing of the entity.

An Approver's invitation is accepted by the button, never by opening the link. Mail security scanners open every link in a message before a person does; if opening it counted, every Approver would be signed up the moment the email arrived.

A role can be changed, or access removed, from the same place. Both take effect on the next request — including for an OAuth app, and for approval links already sent.

When an entity requires approval, each invoice waiting on it sends every Approver an email with their own secure link. If the entity has no Approvers, the owner and Admins are asked instead; Editors and Viewers are never emailed. The link opens the invoice, and the Approver can approve, reject or leave a comment there — the same decision, with the same effect, as Invoices to Approve in the dashboard.

A link stops working when any of these happens:

• the invoice is decided, by anyone — each Approver's copy closes together;
• 7 days pass;
• the person it was sent to is removed from the entity, or made a Viewer.

Each link is issued to one person and records them as the one who decided, so it should not be forwarded. An invoice that failed validation reaches the Approver too, with its errors listed; it can be rejected or commented on, but not approved until it passes.

Require Approval for Sending holds every invoice the entity sends from the dashboard or a connected accounting system. An invoice pushed through the API decides for itself, with bypass_send_approval on POST /oauth/invoices. It defaults to true: the invoice is sent without waiting, even while the entity requires approval.

Every PATCH decides again, with the same default — so a rejected invoice that is corrected and resubmitted without the option is sent; send false to have it approved again. In a bulk push, each invoice decides for itself.

Approval is never a way round validation. An invalid invoice is refused with 422 and nothing is stored, whatever the option says. An invoice that bypasses approval and later fails the check just before sending is not put in front of the Approvers either; it shows as VALIDATION_FAILED for the integration to fix.

An integration that relied on approval for its invoices before this option existed sends "bypass_send_approval": false to keep them waiting.

An OAuth app acts for the person who owns it. It reaches the entities that person can reach, with the role they hold on each:

So an Editor's app can read the entity, update it, and validate, send and update invoices from it — everything an Editor does — except delete the entity.

A Viewer's app can only view: it lists and opens the entity, its sent and received invoices and their status, and every call that would change something answers 403. The sent list covers every invoice sent through the API for the entity, not only the app's own — otherwise an app that cannot send would have nothing to see. Each invoice carries sent_by_this_app, and another app's identifiers are left out. An Approver's app is read-only in the same way: there is no approval endpoint in the API, and approval is done by a person, in the dashboard or from the emailed link. Whether an invoice the app pushes waits for that approval at all is decided per invoice — Invoices pushed through the API.

Only invoices your own app sent can be changed with PATCH, whatever your role.

People follow the application's rules too. The API has no endpoints for inviting people, changing their roles or removing them — an Admin or an Editor does that on the entity details page in the application. What the API does return is who already has access: each entity's users_access lists the members for an Admin's or an Editor's app, and comes back empty for an Approver's or a Viewer's app, who do not see who else has access in the application either. Pending invitations are not returned by the API at all.

POST /oauth/entities follows the account, not a role. On production it answers 403 for everyone, because every entity comes from FTA onboarding. On the development server it answers 403 for an account that was created by accepting an invitation; that account's app still reaches every entity the account was invited to, with the role it holds there.

Every entity in GET /oauth/entities says which case it is, so an integration can decide what to offer before it calls:

{
  "entities": [
    {
      "_id": "66f1c0ffee...",
      "company_name": "ABC Corporation",
      "trn": "100000000000003",
      "access": {
        "role": "editor",
        "via": "member",
        "can_write": true,
        "can_delete": false
      }
    }
  ]
}

There is no connect step. An entity is usable through the API as soon as your app is approved, because the app reaches every entity you own or are a member of — and stops reaching it when your role there ends.

To see the list, sign in and open Entities this app can access on any of your apps under Your apps: each company, its entity_id, your role and what the app may do there. From your integration, GET /oauth/entities returns the same list to the app's own token.

Webhooks follow the same rules. invoice.received goes to every app that can read the receiving entity. Events about a sent invoice go to the app that sent it.

Nothing about entity access is stored in the access token. Membership is read on each request, so removing the app's owner from an entity, or demoting them, changes what the app can do on its very next call. The same applies to invoices: the app lists and reads sent and received invoices only for entities it can still reach.

Users made with POST /oauth/users belong to the app. Entities created for them with user_id are owned by that user and reached by the app as an Admin (via: app). They are separate from people invited to an entity in the application, who hold the roles above.

Resellers are on Reseller accounts. The dashboard walk-through of each role is on Users and roles. Approval in the sending flow is on Sending invoices. Creating an OAuth app is on Create an app, managing it on Your apps, and the entity endpoints are on Entities.