# Klucze i uprawnienia
> Klucze API: jak niesie je żądanie, ich wymiana, ich uprawnienia i odmowy.

Każde żądanie niesie klucz API Twojej firmy w nagłówku `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());
```

## Klucze

Właściciel lub księgowy tworzy klucze w [Ustawienia › Programiści](https://app.ocost.io/settings/api). Ocost pokazuje klucz raz i zachowuje tylko jego odcisk. Jeśli zgubisz klucz, unieważnij go i utwórz nowy.

Początek klucza, `ocost_sk_<id>_`, nie jest tajny. Ustawienia wymieniają klucze według niego, z ich uprawnieniami i ostatnim użyciem. Skanery sekretów rozpoznają wyciek po prefiksie `ocost_sk_`.

Klucz należy do firmy, w której go utworzono. Firma ma najwyżej 10 aktywnych kluczy. Klucz może też wygasać w określonym dniu.

> [!WARNING]
> Trzymaj klucze na swoim serwerze. Nigdy nie umieszczaj klucza w przeglądarce, aplikacji mobilnej ani w logu.

## Spółki grupy

Właściciel grupy spółek może dać kluczowi inne spółki grupy w Ustawienia › Programiści. Klucz sięga wtedy wszystkich, także dodanych później, albo wybranych. Może to też zrobić wsparcie Ocost. Każdą zmianę widać w Ustawieniach jako wizytę Ocost.

`GET /public/v1/businesses` wymienia spółki, do których sięga klucz, najpierw jego własną. Może o to zapytać każdy klucz.

Wskaż spółkę żądania nagłówkiem `Ocost-Business` z jej identyfikatorem. Bez niego żądanie działa we własnej firmie klucza.

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

Klucz i jego sekret pozostają te same, gdy zmieniają się jego spółki. Spółkę, do której już nie sięga, Ocost odrzuca od następnego żądania. Tak samo spółkę, która opuściła grupę.

[Grupy spółek](https://ocost.io/docs/pl/groups.md) wyjaśniają, jak klucz sięga kilku spółek i gdzie trafiają jego pliki.

## Wymiana klucza

1. Utwórz nowy klucz z tymi samymi uprawnieniami.
2. Przełącz na niego swoje oprogramowanie.
3. Unieważnij stary klucz. Ocost odrzuca go już od następnego żądania.

## Uprawnienia

Klucz może robić tylko to, na co pozwalają jego uprawnienia. Ustawienia › Programiści zaznacza nowemu kluczowi pierwsze trzy.

| Uprawnienie | Pozwala na |
| --- | --- |
| `documents:write` | `POST /public/v1/files`, `DELETE /public/v1/files/{file_id}`, `PATCH /public/v1/files/{file_id}`, narzędzie 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 narzędzia MCP czytające rekordy |
| `search:read` | `GET /public/v1/search` i narzędzia wyszukiwania MCP |
| `figures:read` | Narzędzia liczb MCP. Klucz z nim tworzy tylko właściciel. |
| `exports:write` | Narzędzia eksportu MCP |

[Narzędzia MCP](https://ocost.io/docs/pl/tools.md) wymienia każde narzędzie pod jego uprawnieniem.

Żaden klucz nigdy nie czyta dokumentów pracowniczych, takich jak paski płacowe, listy płac czy dokumenty zdrowotne.

## Odmowy

| Odpowiedź | Kiedy |
| --- | --- |
| `401 urn:ocost:key:invalid` | Brak klucza albo klucz zniekształcony, błędny, unieważniony, wygasły lub należący do usuniętej firmy. Odpowiedź jest zawsze taka sama. |
| `403 urn:ocost:key:scope` | Klucz nie ma uprawnienia wymaganego przez trasę. |
| `403 urn:ocost:key:business` | Klucz nie sięga spółki wskazanej w `Ocost-Business`. |
| `400 urn:ocost:key:business` | `Ocost-Business` nie jest identyfikatorem spółki. |
| `429 urn:ocost:key:rate` | Za dużo żądań albo za dużo błędnych kluczy z jednego adresu. Poczekaj `Retry-After` sekund. |
| `400` | Żądanie ma nagłówek `Ocost-View…`, który wysyła tylko aplikacja webowa Ocost. |

## Zobacz też

- [Grupy spółek](https://ocost.io/docs/pl/groups.md): Grupy spółek: do których spółek sięga klucz, nagłówek Ocost-Business, przekierowanie po identyfikatorach dokumentu, needs_company i pliki w grupie.
- [Limity i błędy](https://ocost.io/docs/pl/limits.md): Dokumenty planu na miesiąc, limity wywołań, rozmiary, błędy RFC 9457, ponawianie i miejsce przechowywania danych.
- [Podłączyć asystenta](https://ocost.io/docs/pl/mcp.md): Podłączyć asystenta do serwera MCP (https://api.ocost.io/public/mcp, te same klucze): Claude Code, Claude Desktop, Cursor, claude.ai i ChatGPT przez OAuth oraz każdy klient.
- Na ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
