La API de acceso¶

Esta página es para quien construye una aplicación propia sobre OS y quiere saber qué puede hacer la persona que ha iniciado sesión, para que la aplicación muestre solo botones y menús que funcionen. Muestra cómo haces una solicitud a OS, cómo lees por tipo de cosa lo que alguien puede hacer, y qué significa allowed_actions en cada cosa. Qué son los roles y las reglas está en Roles y acceso.

Una solicitud a OS¶

• Dirección. Toda ruta sobre una organización está bajo /api/v1/organisations/{id}, con el id de la organización (org_...).
• Inicio de sesión. Toda solicitud lleva el token de acceso de la persona que ha iniciado sesión: Authorization: Bearer <token>. OS decide para esa persona, en esa organización.
• Las listas llegan por páginas: limit (como máximo 200, por defecto 50) y cursor. Una respuesta tiene items y, si hay más, next_cursor. Una lista muestra solo lo que la persona puede ver, así que una página puede tener menos filas que limit mientras next_cursor aún continúa.
• Versiones. Una cosa que sustituyes entera (un grupo, un rol propio, un atributo, el documento de reglas) lleva version y la cabecera ETag. Un cambio indica esa versión en If-Match; si la cosa ha cambiado entretanto, OS responde 409.
• Los errores son application/problem+json:

{"type": "about:blank", "title": "Forbidden", "status": 403,
 "detail": "You may grant only what you hold yourself; you do not hold the role org-admin.",
 "request_id": "..."}

Un 422 tiene además errors, una lista con field, message y type por campo.

Lo que alguien puede hacer, por tipo¶

curl -s "$OS/api/v1/organisations/$ORG/access" -H "Authorization: Bearer $TOKEN"

{"organisation_id": "org_...",
 "kinds": [
   {"kind": "organisation", "actions": ["see"]},
   {"kind": "membership", "actions": ["see", "write"]},
   {"kind": "group", "actions": ["see", "write"]},
   ...
 ],
 "core_kinds": [
   {"kind": "model", "actions": ["see", "use"]},
   {"kind": "thread", "actions": ["see", "write", "delete"]},
   ...
 ]}

kinds nombra cada tipo de OS y core_kinds cada tipo de las funciones de IA, siempre todos y en el orden de AccessKind y CoreAccessKind (más abajo). En cada tipo figuran las acciones que la persona puede hacer sobre al menos una cosa de ese tipo. Úsalo para mostrar un menú o un botón «nuevo» antes de haber leído una sola cosa.

La respuesta nunca dice «no» donde algo sí se puede. Puede decir «sí» mientras se rechaza toda cosa que la persona encuentra, por ejemplo si una regla solo vale para cosas con una etiqueta que ninguna lleva. Decide por cosa con allowed_actions.

En las funciones de IA, esto es lo que permiten las reglas de la persona. Una solicitud allí aún puede rechazarse por otro motivo; muestra entonces ese rechazo.

Lo que alguien puede hacer, por cosa¶

Toda cosa que devuelve OS lleva allowed_actions: las acciones que la persona puede hacer sobre exactamente esa cosa. Muestra un botón solo si la acción está en la lista; la solicitud detrás del botón tiene entonces éxito.

Una organización tiene además una segunda lista, parent_allowed_actions: lo que la persona puede hacer sobre ella en la organización superior. write allí es suspender, reanudar y sustituir las etiquetas; delete es eliminar. Para la organización más alta, y para quien no llega a la organización superior, esa lista está vacía.

El servicio de una organización tiene las mismas dos listas: en parent_allowed_actions, write significa que la persona puede dar y quitar allí planes y excepciones y fijar la fecha de fin de una demo.

Por tipo y por cosa, todo vale dentro del servicio de la organización: lo que no está en él, no está en ninguna de las dos listas.

Los nombres en el esquema¶

Los tipos y las acciones son enumeraciones en el esquema OpenAPI de OS, con nombres fijos, para que puedas crear tus propios tipos a partir de ellos: