[Intum Pomoc](https://intum.pl/pomoc.md) / [API](https://intum.pl/pomoc/konto/api.md)

# [Tokeny API konta](https://intum.pl/pomoc/konto/api/tokeny-api.md)

Tworzenie, aktualizacja, usuwanie i listowanie tokenów API konta. Token API służy do
autoryzacji requestów do API Intuma (`Authorization: Bearer TOKEN`). Token może być
zawężony do wybranych uprawnień i mieć termin ważności.

**Autoryzacja:** `Authorization: Bearer TOKEN`
**Content-Type:** `application/json; charset=utf-8`

## API Endpoints

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/account/api_tokens.json` | Lista twoich tokenów |
| GET | `/account/api_tokens.json?for_account=yes` | Lista tokenów całego konta |
| GET | `/account/api_tokens/:id.json` | Pojedynczy token |
| POST | `/account/api_tokens.json` | Utworzenie tokena |
| PATCH | `/account/api_tokens/:id.json` | Aktualizacja tokena |
| DELETE | `/account/api_tokens/:id.json` | Usunięcie tokena |

## Pola tokena

| Pole | Typ | Wymagane | Opis |
|------|-----|----------|------|
| `name` | string | nie | Nazwa opisowa - po co ten token (np. `"Integracja Fakturownia"`) |
| `code` | string | nie | Kod tokena, unikalny w koncie - do odwoływania się z konfiguracji |
| `active` | boolean | nie | Czy token działa (domyślnie `true`) |
| `expires_at` | date/datetime | nie | Termin ważności; puste = bez terminu |
| `kind` | string | nie | Puste = zwykły token API, `"web_token"` = token do sesji web/autologowania |
| `integration_app_code` | string | nie | Kod aplikacji integracyjnej, unikalny w koncie |
| `for_account` | boolean | nie | `true` = token całego konta (nie tylko twój); takich tokenów API nie usuwa |
| `privileges` | array | nie | Lista uprawnień zawężających token; puste = uprawnienia użytkownika-właściciela |

Zasady:

- **Surowy token zwracany jest tylko w odpowiedzi na POST** - to jedyny moment, kiedy da się go
  odczytać. Później API i widoki pokazują wyłącznie zamaskowany fragment (`token_info`)
- `code` i `integration_app_code` muszą być unikalne w ramach konta - duplikat to błąd walidacji
- token nieaktywny (`active: false`) lub po `expires_at` nie autoryzuje requestów
- `privileges` zawężają, nigdy nie rozszerzają - token nie dostanie uprawnienia,
  którego nie ma jego użytkownik
- DELETE na tokenie z `for_account: true` nie usuwa go (żeby nie zerwać działającej integracji)

## Format requestu

### POST - token dla integracji, zawężony i z terminem

```
POST /account/api_tokens.json
Authorization: Bearer TOKEN
Content-Type: application/json; charset=utf-8
```

```json
{
  "api_token": {
    "name": "Integracja Fakturownia",
    "code": "fakturownia_sync",
    "expires_at": "2027-01-01",
    "privileges": ["commerce_invoices", "crm_clients_access"]
  }
}
```

Odpowiedź (201 Created) zawiera surowy `token` - zapisz go od razu:

```json
{
  "id": 123,
  "token": "intm_...",
  "kind": null,
  "name": "Integracja Fakturownia",
  "for_account": false,
  "integration_app_code": null,
  "expires_at": "2027-01-01",
  "active": true
}
```

### PATCH - wyłączenie tokena

```json
{
  "api_token": {
    "active": false
  }
}
```

### Błąd walidacji (422 Unprocessable Content)

```json
{
  "errors": { "code": ["zostało już zajęte"] }
}
```

## Powiązane

- [common_api](https://app.intum.pl/noe/prompt/common_api.md) - wspólne zasady API (format, autoryzacja, odpowiedzi)
- [account_webhooks_api](https://intum.intum.pl/kb/intum-kb/konto/api/webhooki) - webhooki konta (token dołączany do requestu POST)