# Chei și drepturi
> Chei API: cum le poartă o cerere, înlocuirea lor, drepturile lor și refuzurile.

Fiecare cerere poartă cheia API a firmei dumneavoastră în antetul `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());
```

## Chei

Proprietarul sau contabilul creează cheile în [Setări › Dezvoltatori](https://app.ocost.io/settings/api). Ocost arată o cheie o singură dată și păstrează doar o amprentă a ei. Dacă pierdeți o cheie, revocați-o și creați una nouă.

Începutul unei chei, `ocost_sk_<id>_`, nu este secret. Setările listează cheile după el, cu drepturile și ultima utilizare. Scanerele de secrete recunosc prefixul `ocost_sk_` într-o scurgere de date.

O cheie aparține firmei în care a fost creată. O firmă are cel mult 10 chei active. O cheie poate și să expire la o anumită dată.

> [!WARNING]
> Păstrați cheile pe serverul dumneavoastră. Nu puneți niciodată o cheie într-un browser, într-o aplicație mobilă sau într-un jurnal.

## Societățile unui grup

Proprietarul unui grup de societăți poate da unei chei alte societăți ale grupului în Setări › Dezvoltatori. Cheia ajunge atunci la toate, inclusiv la cele adăugate mai târziu, sau la o selecție. Le poate stabili și suportul Ocost. Fiecare schimbare apare în Setări ca o vizită Ocost.

`GET /public/v1/businesses` listează societățile la care ajunge o cheie, întâi pe a sa. Orice cheie poate întreba.

Numiți societatea unei cereri cu antetul `Ocost-Business`, identificatorul ei. Fără el, cererea acționează în firma cheii.

```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());
```

Cheia și secretul ei rămân aceleași când i se schimbă societățile. O societate la care nu mai ajunge este refuzată de la următoarea cerere. La fel o societate care părăsește grupul.

[Grupuri de firme](https://ocost.io/docs/ro/groups.md) explică cum ajunge o cheie la mai multe societăți și unde ajung fișierele ei.

## Înlocuiți o cheie

1. Creați o cheie nouă cu aceleași drepturi.
2. Treceți software-ul dumneavoastră pe ea.
3. Revocați cheia veche. Ocost o refuză chiar de la următoarea cerere.

## Drepturi

O cheie poate face doar ce îi permit drepturile. Setări › Dezvoltatori le bifează pe primele trei pentru o cheie nouă.

| Drept | Permite |
| --- | --- |
| `documents:write` | `POST /public/v1/files`, `DELETE /public/v1/files/{file_id}`, `PATCH /public/v1/files/{file_id}`, instrumentul 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}` și instrumentele MCP care citesc înregistrări |
| `search:read` | `GET /public/v1/search` și instrumentele de căutare ale MCP |
| `figures:read` | Instrumentele de cifre ale MCP. Doar proprietarul creează o cheie cu acest drept. |
| `exports:write` | Instrumentele de export ale MCP |

[Instrumente MCP](https://ocost.io/docs/ro/tools.md) listează fiecare instrument sub dreptul său.

Nicio cheie nu citește vreodată actele personale ale oamenilor, de exemplu fluturașii de salariu, statele de plată sau actele medicale.

## Refuzuri

| Răspuns | Când |
| --- | --- |
| `401 urn:ocost:key:invalid` | Nicio cheie, o cheie greșit formată, greșită, revocată sau expirată, ori cheia unei firme șterse. Răspunsul este mereu același. |
| `403 urn:ocost:key:scope` | Cheii îi lipsește dreptul rutei. |
| `403 urn:ocost:key:business` | Cheia nu ajunge la societatea pe care o numește `Ocost-Business`. |
| `400 urn:ocost:key:business` | `Ocost-Business` nu este identificatorul unei societăți. |
| `429 urn:ocost:key:rate` | Prea multe cereri sau prea multe chei greșite de la o adresă. Așteptați `Retry-After` secunde. |
| `400` | Cererea are un antet `Ocost-View…`, pe care doar aplicația web Ocost îl trimite. |

## Vezi și

- [Grupuri de firme](https://ocost.io/docs/ro/groups.md): Grupuri de firme: la ce societăți ajunge o cheie, antetul Ocost-Business, redirecționarea după identificatorii documentului, needs_company și fișierele din grup.
- [Limite și erori](https://ocost.io/docs/ro/limits.md): Documentele lunare ale planului, limitele de rată, dimensiunile, erorile RFC 9457, reîncercările și unde sunt păstrate datele.
- [Conectați un asistent](https://ocost.io/docs/ro/mcp.md): Conectați un asistent la serverul MCP (https://api.ocost.io/public/mcp, aceleași chei): Claude Code, Claude Desktop, Cursor, claude.ai și ChatGPT prin OAuth, și orice client.
- Pe ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
