Claves y permisos
Cada solicitud lleva la clave de API de tu empresa en la cabecera Authorization:
Authorization: Bearer ocost_sk_<id>_<secret>curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY"import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()const files = await fetch('https://api.ocost.io/public/v1/files', {
headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());Claves
- PrefijoLos escáneres de secretos lo detectan en una fuga.
- Id públicoNo es secreto. Ajustes lista las claves por él.
- SecretoSe muestra una vez. Guárdalo en tu servidor.
Authorization: Bearer ocost_sk_…- Cada petición
Ocost-Business: <id>- Una empresa del grupo, opcional
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.
Ocost-Business: 018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
-H "Ocost-Business: $COMPANY_ID"files = session.get(
"https://api.ocost.io/public/v1/files",
headers={"Ocost-Business": company_id},
timeout=15,
).json()const files = await fetch('https://api.ocost.io/public/v1/files', {
headers: { Authorization: `Bearer ${key}`, 'Ocost-Business': companyId },
}).then((r) => r.json());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
- Crea una clave nueva con los mismos permisos.
- Cambia tu software a ella.
- 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.
| Permiso | Permite |
|---|---|
documents:write | POST /public/v1/files, DELETE /public/v1/files/{file_id}, PATCH /public/v1/files/{file_id}, la herramienta MCP send_file |
documents:read | GET /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:read | GET /public/v1/search y las herramientas de búsqueda del MCP |
figures:read | Las herramientas de cifras del MCP. Solo el propietario crea una clave con él. |
exports:write | Las 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
| Respuesta | Cuándo |
|---|---|
401 urn:ocost:key:invalid | Ninguna 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:scope | A la clave le falta el permiso de la ruta. |
403 urn:ocost:key:business | La clave no llega a la sociedad que nombra Ocost-Business. |
400 urn:ocost:key:business | Ocost-Business no es el identificador de una sociedad. |
429 urn:ocost:key:rate | Demasiadas solicitudes, o demasiadas claves erróneas desde una dirección. Espera Retry-After segundos. |
400 | La solicitud lleva una cabecera Ocost-View…, que solo envía la app web de Ocost. |