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.
The tenant slug
Section titled “The tenant slug”Each tenant route has the slug of its tenant after /api/v1/:
/api/v1/<tenant>/.../api/v1/acme/masters/itemsThe 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) |
Membership and roles
Section titled “Membership and roles”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.
Access roles
Section titled “Access roles”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.
Modules
Section titled “Modules”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/....
Credentials and access
Section titled “Credentials and access”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. |
Storages
Section titled “Storages”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.
Suspended tenants
Section titled “Suspended tenants”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.