Skip to content

Tenants and access

A tenant is one company in Posto. Each tenant has its own data. The API keeps the tenants apart in the database: a request reads and writes only the rows of its tenant.

Each tenant route has the slug of its tenant after /api/v1/:

/api/v1/<tenant>/...
/api/v1/acme/masters/items

The slug is the short name of the tenant in the ERP address, for example https://app.postoerp.com/acme/. A slug cannot be a reserved word of the platform, such as platform, api, auth or version.

Request Answer
Unknown slug 404 “The company does not exist.”
A tenant where the caller is not a member 403 “No access to this company.”
A key or a token of another tenant 403 “The API key is not valid for this company.” (or the same text for an OAuth token)

A caller must be a member of the tenant. Each member has one role:

Role Access
owner Full access to every module of the tenant.
admin Full access to every module of the tenant, except the activity log. An admin reads the activity log only through an access role.
member Only the rights of the access roles that the member has.

GET /api/v1/<tenant>/me returns the role in access.role.

An access role is a list of grants. A grant gives rights on one feature, such as sales.invoices, or on every feature of a module, such as sales.*:

Right Values
Read none, own records, all records
Create yes or no
Write own, write other Change, confirm, convert and post own records or records of other users
Delete own, delete other Delete own records or records of other users

An “own” record is a record that the caller created. Each right stands alone: a write right gives no create or delete right.

When a member can read only their own records, a list returns only those records.

A tenant has a set of modules. The modules masters and system are in every tenant. A route of a module that the tenant does not have gets 403, for every caller.

The first segment of a tenant route is its module: /sales/..., /inventory/..., /masters/....

The rights of a request come from the credential:

Credential Rights
Personal API key The role and the access roles of the key owner
Service API key The access roles of the key. Its user is a member.
OAuth user token The role and the access roles of the user, limited by the module scopes of the token
Server client token The access roles of the client, limited by the module scopes of the token. Its user is a member.

A user who manages the members can assign storages to a member. The owner is never limited. A member with assigned storages works only with the documents of those storages. The API hides a document of another storage, and it refuses a write that names one. A member without assigned storages works with every storage.

A tenant can be suspended. Then each write gets 403 with the code tenant_suspended. Reads still work. GET /me returns the time and the reason in suspended.