Una organización es un cliente de Arbol, como una clínica: sus miembros, API keys, conexiones, facturación y datos. Cada credencial está ligada a exactamente una organización, y cada llamada que hace actúa en esa organización.
Una organización por credencial
| Credencial | Su organización |
|---|---|
| API key | La organización en la que se creó. |
| Token de una aplicación de máquina | La organización a la que pertenece la aplicación. |
| El token de una persona | La organización que la persona seleccionó al iniciar sesión. |
Para ver de qué organización es una credencial, llama a account.organization.get. Acepta todo tipo de credencial y solo necesita el permiso (scope) account:organizations:read.
El límite entre organizaciones
Nada en una solicitud mueve una llamada a otra organización. Ningún parámetro cambia de organización: la organización sale de la credencial.
- Las listas contienen solo los registros de tu organización. Una lista responde con los elementos de la organización verificada y nada más.
- Los registros de otras organizaciones están fuera de alcance. Por ejemplo, Raíz responde
RESOURCE_NOT_FOUND(“The requested resource does not exist in this organization”), y Visoft respondeNOT_FOUNDpara la conexión de otra organización. - Para trabajar en otra organización, usa una credencial ligada a ella. Crea una API key en esa organización o inicia sesión en ella.
Una persona puede pertenecer a varias organizaciones. account.organizations.list responde con las organizaciones a las que pertenece la persona con sesión iniciada, con current: true en aquella para la que es su token. Para actuar en otra, la persona inicia sesión en ella y obtiene un token para esa organización.
Personas y máquinas
La API distingue dos tipos de quien llama:
| Quién llama | Credenciales |
|---|---|
| Una persona | El token de acceso de una persona, al iniciar sesión |
| Una máquina | Una API key, o el token de client credentials de una aplicación de máquina |
La mayoría de las operaciones aceptan ambos. Unas pocas aceptan solo personas: su página en la referencia de la API dice Credentials: a person’s access token only (solo el token de una persona). Una credencial de máquina recibe 403 al llamarlas. Son:
- En Cuenta:
account.organizations.listyaccount.permissions.list. - En Agenda: crear, reprogramar y cambiar el estado de las citas, como
agenda.appointments.create, y crear o actualizar servicios, ofertas, recursos y reglas de horario, comoagenda.services.update.
Las máquinas agendan citas de Agenda con las operaciones de agendamiento, como agenda.bookings.create.
Permisos
Los permisos son scopes, con nombres de la forma <service>:<resource>:<access>, como agenda:appointments:read. Cómo los obtiene quien llama depende de quién es:
- Las personas los obtienen de sus roles. Los miembros tienen roles en los productos de Arbol: Raíz, Agenda, Ámbar y Cuenta.
account.roles.listmuestra los permisos de cada rol, yaccount.members.listmuestra quién tiene qué roles. El token de una persona cuenta un scope solo hasta donde sus roles lo otorgan. - Las máquinas obtienen los scopes que se les otorgan. Una API key lleva los scopes que se eligieron al crearla, y una key nunca lleva un permiso que no tenga quien la creó. Una key también se puede restringir, por integración, a algunas de sus operaciones y conexiones.
Los scopes que acepta cada operación están en su página de la referencia de la API. Consulta Permisos (scopes).
Conexiones
Las integraciones funcionan a través de las conexiones de la organización con cada sistema, que configura el equipo de Arbol. account.connections.list las lista.
Una operación que corre sobre una conexión llega solo a las conexiones de la propia organización. connectionId elige la conexión: es opcional mientras la organización tenga una sola conexión con ese sistema, y necesario cuando tiene varias. Consulta Integraciones.