Claves y permisos

Cada solicitud lleva la clave de API de tu empresa en la cabecera Authorization:

Text
Authorization: Bearer ocost_sk_<id>_<secret>
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"

Claves

El propietario o el contable crean claves en Ajustes › Desarrolladores. Ocost muestra una clave una vez y solo guarda una huella. Si pierdes una clave, revócala y crea una nueva.

El inicio de una clave, ocost_sk_<id>_, no es secreto. Ajustes lista las claves por él, con sus permisos y su último uso. Los escáneres de secretos detectan una fuga por el prefijo ocost_sk_.

Una clave pertenece a la empresa en la que se creó. Una empresa tiene como máximo 10 claves activas. Una clave también puede caducar en una fecha.

Atención

Guarda las claves en tu servidor. Nunca pongas una en un navegador, una app móvil o un log.

Las sociedades de un grupo

El propietario de un grupo de sociedades puede dar a una clave otras sociedades del grupo en Ajustes › Desarrolladores. La clave llega entonces a todas, también a las que se añadan después, o a una selección. El soporte de Ocost también puede fijarlas. Cada cambio aparece en Ajustes como una visita de Ocost.

GET /public/v1/businesses lista las sociedades a las que llega una clave, la suya primero. Cualquier clave puede preguntarlo.

Nombre la sociedad de una petición con la cabecera Ocost-Business, su identificador. Sin ella, la petición actúa en la empresa de la clave.

Text
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"

La clave y su secreto siguen siendo los mismos cuando cambian sus sociedades. Una sociedad a la que ya no llega se rechaza desde la siguiente petición. Igual que una sociedad que deja el grupo.

Grupos de empresas explica cómo una clave llega a varias sociedades y dónde acaban sus archivos.

Rotar una clave

  1. Crea una clave nueva con los mismos permisos.
  2. Cambia tu software a ella.
  3. Revoca la clave antigua. Ocost la rechaza desde la siguiente solicitud.

Permisos

Una clave solo puede hacer lo que sus permisos permiten. Ajustes › Desarrolladores marca los tres primeros para una clave nueva.

PermisoPermite
documents:writePOST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, la herramienta MCP send_file
documents:readGET /public/v1/files, GET /public/v1/files/{file_id}, GET /public/v1/files/{file_id}/content, GET /public/v1/files/{file_id}/document, GET /public/v1/documents/{document_id} y las herramientas MCP que leen registros
search:readGET /public/v1/search y las herramientas de búsqueda del MCP
figures:readLas herramientas de cifras del MCP. Solo el propietario crea una clave con él.
exports:writeLas herramientas de exportación del MCP

Herramientas MCP lista cada herramienta bajo su permiso.

Ninguna clave lee nunca los papeles de las personas, como nóminas, listas de sueldos o papeles de salud.

Rechazos

RespuestaCuándo
401 urn:ocost:key:invalidNinguna clave, o una mal formada, errónea, revocada o caducada, o la de una empresa borrada. La respuesta es siempre la misma.
403 urn:ocost:key:scopeA la clave le falta el permiso de la ruta.
403 urn:ocost:key:businessLa clave no llega a la sociedad que nombra Ocost-Business.
400 urn:ocost:key:businessOcost-Business no es el identificador de una sociedad.
429 urn:ocost:key:rateDemasiadas solicitudes, o demasiadas claves erróneas desde una dirección. Espera Retry-After segundos.
400La solicitud lleva una cabecera Ocost-View…, que solo envía la app web de Ocost.

Véase también