---
title: "Organizations"
description: "Every credential acts in one organization. The organization boundary, people and machines, and their permissions."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

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`](/api/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 answers `NOT_FOUND` for 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`](/api/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.list`](/api/account/organizations/list/) and [`account.permissions.list`](/api/account/permissions/list/).
- In Agenda: creating, rescheduling and setting the status of appointments, such as [`agenda.appointments.create`](/api/agenda/appointments/create/), and creating or updating services, offerings, resources and schedule rules, such as [`agenda.services.update`](/api/agenda/services/update/).

Machines book Agenda appointments through the booking operations instead, such as [`agenda.bookings.create`](/api/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.list`](/api/account/roles/list/) shows each role's permissions, and [`account.members.list`](/api/account/members/list/) shows 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](/en/developers/authentication/#scopes).

## Connections

The [integrations](/en/developers/integrations/) work through the organization's connections to each system, which the Arbol team sets up. [`account.connections.list`](/api/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](/en/developers/integrations/#connections).

Source: https://docs.getarbol.com/en/developers/concepts/organizations/index.mdx