# Claves y permisos
> Claves de API: cómo las lleva una solicitud, cómo rotarlas, sus permisos y los rechazos.

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

```text
Authorization: Bearer ocost_sk_<id>_<secret>
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY"
```

```python
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
files = session.get("https://api.ocost.io/public/v1/files", timeout=15).json()
```

```javascript
const files = await fetch('https://api.ocost.io/public/v1/files', {
  headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
```

## Claves

El propietario o el contable crean claves en [Ajustes › Desarrolladores](https://app.ocost.io/settings/api). 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.

> [!WARNING]
> 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
```

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: $COMPANY_ID"
```

```python
files = session.get(
    "https://api.ocost.io/public/v1/files",
    headers={"Ocost-Business": company_id},
    timeout=15,
).json()
```

```javascript
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](https://ocost.io/docs/es/groups.md) 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.

| 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](https://ocost.io/docs/es/tools.md) 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. |

## Véase también

- [Grupos de empresas](https://ocost.io/docs/es/groups.md): Grupos de empresas: a qué sociedades llega una clave, la cabecera Ocost-Business, el enrutado por los identificadores del documento, needs_company y los archivos del grupo.
- [Límites y errores](https://ocost.io/docs/es/limits.md): Los documentos al mes del plan, los límites de frecuencia, los tamaños, los errores RFC 9457, los reintentos y dónde se guardan los datos.
- [Conectar un asistente](https://ocost.io/docs/es/mcp.md): Conectar un asistente al servidor MCP (https://api.ocost.io/public/mcp, las mismas claves): Claude Code, Claude Desktop, Cursor, claude.ai y ChatGPT por OAuth, y cualquier cliente.
- En ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
