An organization is one Arbol customer, such as a clinic: its members, API keys, connections, billing and data. Every credential is bound to exactly one organization, and every call it makes acts in that organization.
One organization per credential
| Credential | Its organization |
|---|---|
| API key | The organization it was created in. |
| Machine application token | The organization the application belongs to. |
| A person’s token | The organization the person selected when they signed in. |
To see which organization a credential is for, call account.organization.get. It accepts every kind of credential and needs only the account:organizations:read scope.
The organization boundary
Nothing in a request moves a call into another organization. No parameter switches organizations: the organization comes from the credential.
- Lists hold only your organization’s records. A list answers the items of the verified organization and nothing else.
- Other organizations’ records are out of reach. For example, Raíz answers
RESOURCE_NOT_FOUND(“The requested resource does not exist in this organization”), and Visoft answersNOT_FOUNDfor another organization’s connection. - To work in another organization, use a credential bound to it. Create an API key in that organization, or sign in to it.
A person can belong to several organizations. account.organizations.list answers the organizations the signed-in person belongs to, with current: true on the one their token is for. To act in another one, the person signs in to it and gets a token for that organization.
People and machines
The API tells two kinds of callers apart:
| Caller | Credentials |
|---|---|
| A person | A person’s access token, from signing in |
| A machine | An API key, or a machine application’s client-credentials token |
Most operations accept both. A few accept only people: their page in the API reference says Credentials: a person’s access token only. A machine credential gets 403 when it calls them. They are:
- In Account:
account.organizations.listandaccount.permissions.list. - In Agenda: creating, rescheduling and setting the status of appointments, such as
agenda.appointments.create, and creating or updating services, offerings, resources and schedule rules, such asagenda.services.update.
Machines book Agenda appointments through the booking operations instead, such as agenda.bookings.create.
Permissions
Permissions are scopes, named <service>:<resource>:<access>, such as agenda:appointments:read. How a caller gets them depends on who it is:
- People get them from roles. Members hold roles in Arbol’s products: Raíz, Agenda, Ámbar and Account.
account.roles.listshows each role’s permissions, andaccount.members.listshows who holds which roles. A person’s token counts a scope only as far as their roles grant it. - Machines get the scopes they’re granted. An API key carries the scopes chosen when it was created, and a key never carries a permission its creator lacks. A key can also be restricted, per integration, to some of its operations and connections.
The scopes each operation accepts are on its page in the API reference. See Scopes.
Connections
The integrations work through the organization’s connections to each system, which the Arbol team sets up. account.connections.list lists them.
An operation that runs on a connection reaches only the organization’s own connections. connectionId picks the connection: it’s optional while the organization has one connection to that system, and needed when it has several. See Integrations.