Portals and companies

Before you write your first request, it is worth understanding what the Yuki API considers "your data". Almost every question that comes up later — why a call returns fewer records than expected, why two users of the same application see different results — comes back to the relationship between a portal, its companies and the user who signed in.

This page is conceptual. For the requests themselves, see the Authentication and Authorization Guide and the API reference.

Portals and companies

A portal is the accounting office or organization that Yuki knows you by. It is the top of the structure and the thing a subscription belongs to.

A company sits under a portal. It is the administration that actually holds accounting data: the contacts, the invoices, the ledger entries, the VAT settings. A portal can hold one company or many hundreds of them.

The distinction matters because a portal on its own holds very little of what you probably came here for. The data your application reads and writes lives in the companies, and it is separated per company — two companies under the same portal do not share their bookkeeping.

Between the two sits a domain, the grouping Yuki uses to organize companies within a portal. You will meet it in the API reference, and it is how a set of companies is addressed together.

What your application can reach

The most important thing to understand is this: access is granted per company, to the signed-in user — not to your application.

Your application does not hold a standing right to any company's data. What it holds is the ability to ask a user to sign in, and the scopes that were approved for its integration. When that user signs in, your application acts on their behalf and inherits their reach:

Scopes decide what kinds of operation your application may perform at all — reading domains, writing domains, and so on. A scope your integration was not approved for is unavailable no matter who signs in.
The signed-in user decides which companies those operations can touch. A user who can reach three of a portal's forty companies gives your application three companies, not forty.

Both have to line up. If a call is refused, check which of the two is missing before changing anything else: an operation your scopes do not cover fails for every user, while an operation on a company the user cannot reach fails only for that user.

A practical consequence for anyone building for several customers: your application is registered once, but its reach is different for every user who signs in. Do not cache "what this application can see" globally, and do not assume that because one user could read a company, the next one can.

Many users can reach exactly one company, and for them nothing needs to be chosen — your application simply receives that company.

When a user can reach more than one, the choice is made during sign-in, before the user comes back to your application. Yuki presents the companies that user can reach, the user picks one, and your application receives the selected company along with the rest of the sign-in result.

Two things follow from this that are easy to get wrong:

Your application does not make this choice, and cannot make it silently. You cannot pre-select a company on the user's behalf as part of the sign-in request.
The selection belongs to that sign-in. If a user needs to work in a different company, they go through sign-in again and choose it. Treat the selected company as part of the session you were handed, not as a durable setting for that user.

Read the selected company from the sign-in result rather than inferring it. If your application assumes the user's only or first company, it will work for single-company users and quietly read the wrong books for everyone else.

Presenting your own company picker

Receiving one selected company is enough for many applications. But if yours shows data from several companies side by side — a consolidated overview, a report across a customer's whole portfolio — you will want your own picker rather than sending the user back through sign-in each time.

You can do that. Once a user has signed in, your application can ask the Yuki API which portal that user belongs to and which companies they can reach, and use the answer to build its own list. Two rules keep this honest:

Ask, per user, after sign-in. The answer describes that user, so it belongs to their session. Refresh it rather than storing it indefinitely — a user's access changes over time, and a picker built from a stale list will offer companies that no longer work.
Show only what came back. Do not offer every company in the portal and let the API refuse the ones the user cannot reach. That turns a clear "you do not have access to this" into a confusing error in the middle of your application.

How this maps to the API reference

The concepts on this page appear in the API reference as resources you can address directly:

Portal — the accounting office or organization at the top of the structure. Use it to confirm which portal the signed-in user belongs to.
Domain — the grouping of companies within a portal. Use it to address a set of companies together.
Company — the individual administration holding the accounting data. This is the level most operations work at, and the level access is granted at.

The reference is the authoritative source for the operations available on each of these and the scopes each one requires. Start from the concept you need here, then look up the resource there.

If something does not behave as this page describes, contact Yuki support — and see API error codes for what the API returns when a request is refused.

Portals and companies