API pro tajemství¶

Vytváření, čtení, aktualizace, mazání, rotace a sdílení tajemství

Verze dokumentu: 1.1.0
Poslední aktualizace: 2026-04-04

Přehled endpointů¶

Metoda	Endpoint	Popis
POST	`/api/v1/secrets`	Vytvořit nové tajemství
GET	`/api/v1/secrets`	Zobrazit tajemství v projektu
GET	`/api/v1/secrets/:id`	Získat tajemství podle ID
PUT	`/api/v1/secrets/:id`	Aktualizovat tajemství
DELETE	`/api/v1/secrets/:id`	Smazat tajemství (softdel)
GET	`/api/v1/secrets/:id/versions`	Zobrazit verze tajemství
POST	`/api/v1/secrets/:id/rollback`	Vrátit se k předchozí verzi
POST	`/api/v1/secrets/:id/copy`	Kopírovat tajemství
POST	`/api/v1/secrets/:id/archive`	Archivovat tajemství
POST	`/api/v1/secrets/:id/restore`	Obnovit archivované tajemství
DELETE	`/api/v1/secrets/:id/permanent`	Trvale smazat tajemství
POST	`/api/v1/secrets/:id/rotate`	Spustit rotaci tajemství
GET	`/api/v1/secrets/:id/rotation-config`	Získat konfiguraci rotace
PUT	`/api/v1/secrets/:id/rotation-config`	Aktualizovat konfiguraci rotace
GET	`/api/v1/secrets/:id/sync-status`	Získat stav synchronizace
POST	`/api/v1/secrets/:id/force-sync`	Vynutit synchronizaci
POST	`/api/v1/secrets/:id/environments/:env/force-sync`	Vynutit synchronizaci pro prostředí
GET	`/api/v1/secrets/:id/links`	Zobrazit vazby tajemství↔integrace
POST	`/api/v1/secrets/:id/links`	Vytvořit vazbu tajemství
DELETE	`/api/v1/secrets/:id/links/:linkId`	Smazat vazbu tajemství

Vytvoření tajemství¶

POST /api/v1/secrets HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "database-password",
  "value": "s3cur3P@ssw0rd!",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "environment": "production",
  "ttl_hours": 2160,
  "metadata": {
    "owner": "dba-team",
    "service": "postgres-main"
  },
  "change_reason": "Počáteční vytvoření hesla databáze"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`key`	string	✅	Název klíče tajemství (unikátní v rámci projektu, 1–255 znaků)
`value`	string	✅	Hodnota tajemství (šifrovaná při uložení, max 64 KB)
`project_id`	string	✅	ID cílového projektu (UUID)
`environment`	string	—	Rozsah prostředí (např. `production`, `staging`; max 50 znaků)
`ttl_hours`	integer	—	Doba životnosti v hodinách (1–8760; tajemství po této době expiruje)
`metadata`	object	—	Libovolná metadata klíč-hodnota pro organizaci
`change_reason`	string	—	Auditní důvod pro vytvoření tajemství (max 1000 znaků)

Odpověď `201 Created`¶

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "stored"
}

Bezpečnost

Hodnota tajemství (value) je vrácena pouze přes GET /secrets/:id s příslušnými oprávněními. Endpointy pro výpis hodnoty nezahrnují.

Výpis tajemství¶

GET /api/v1/secrets?project_id=550e8400-e29b-41d4-a716-446655440001&page=1&per_page=25 HTTP/1.1
Authorization: Bearer <token>

Parametry dotazu¶

Parametr	Typ	Popis
`project_id`	string	Filtrovat podle projektu (povinný)
`environment`	string	Filtrovat podle prostředí
`search`	string	Vyhledávat podle názvu klíče
`page`	integer	Číslo stránky (výchozí: 1)
`per_page`	integer	Položek na stránku (výchozí: 25, max: 100)

Odpověď `200 OK`¶

{
  "data": [
    {
      "id": "sec_xyz789",
      "name": "database-password",
      "type": "password",
      "description": "Production database master password",
      "version": 3,
      "tags": ["production", "database"],
      "rotation": {
        "enabled": true,
        "next_rotation": "2026-05-11T00:00:00Z"
      },
      "created_at": "2026-02-10T14:30:00Z",
      "updated_at": "2026-02-10T16:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Získání tajemství¶

GET /api/v1/secrets/sec_xyz789 HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "id": "sec_xyz789",
  "name": "database-password",
  "value": "s3cur3P@ssw0rd!",
  "type": "password",
  "description": "Production database master password",
  "version": 3,
  "tags": ["production", "database"],
  "project_id": "proj_abc123",
  "rotation": {
    "enabled": true,
    "interval_days": 90,
    "next_rotation": "2026-05-11T00:00:00Z",
    "last_rotated": "2026-02-10T14:30:00Z"
  },
  "created_at": "2026-02-10T14:30:00Z",
  "updated_at": "2026-02-10T16:45:00Z",
  "created_by": "usr_abc123"
}

Audit

Každý požadavek GET, který získá dešifrovanou hodnotu tajemství, je zaznamenán v auditním logu.

Aktualizace tajemství¶

PUT /api/v1/secrets/sec_xyz789 HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "value": "n3wS3cur3P@ss!",
  "description": "Updated production database password"
}

Aktualizovatelná pole¶

Pole	Popis
`value`	Nová hodnota tajemství (vytvoří novou verzi)
`description`	Aktualizovaný popis
`tags`	Aktualizované štítky
`rotation.enabled`	Povolit/zakázat rotaci
`rotation.interval_days`	Aktualizovat interval rotace

Odpověď `200 OK`¶

Vrátí aktualizovaná metadata tajemství (hodnota není zahrnuta).

Smazání tajemství¶

DELETE /api/v1/secrets/sec_xyz789 HTTP/1.1
Authorization: Bearer <token>

Odpověď `204 No Content`¶

Softdel vs trvalé smazání

DELETE /secrets/:id provede softdel. Tajemství lze obnovit přes POST /secrets/:id/restore. Pro trvalé, nevratné smazání použijte DELETE /secrets/:id/permanent.

Archivace a obnovení¶

Archivovat tajemství¶

POST /api/v1/secrets/sec_xyz789/archive HTTP/1.1
Authorization: Bearer <token>

Přesune tajemství do archivu. Archivovaná tajemství nejsou dostupná přes běžné dotazy.

Obnovit tajemství¶

POST /api/v1/secrets/sec_xyz789/restore HTTP/1.1
Authorization: Bearer <token>

Obnoví dříve archivované tajemství zpět do aktivního stavu.

Trvalé smazání¶

DELETE /api/v1/secrets/sec_xyz789/permanent HTTP/1.1
Authorization: Bearer <token>

Nevratné

Trvalé smazání nelze vrátit zpět. Všechny verze budou odstraněny.

Kopírování tajemství¶

POST /api/v1/secrets/sec_xyz789/copy HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Zkopíruje tajemství do jiného projektu nebo prostředí.

Verze tajemství¶

Výpis verzí¶

GET /api/v1/secrets/sec_xyz789/versions HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "data": [
    {
      "version": 3,
      "created_at": "2026-02-10T16:45:00Z",
      "created_by": "usr_abc123",
      "change_type": "manual_update"
    },
    {
      "version": 2,
      "created_at": "2026-01-15T10:00:00Z",
      "created_by": "system",
      "change_type": "rotation"
    },
    {
      "version": 1,
      "created_at": "2026-02-10T14:30:00Z",
      "created_by": "usr_abc123",
      "change_type": "initial"
    }
  ]
}

Návrat k předchozí verzi¶

POST /api/v1/secrets/sec_xyz789/rollback HTTP/1.1
Authorization: Bearer <token>

Vytvoří novou verzi s hodnotou z předchozí verze.

Rotace tajemství¶

Získat konfiguraci rotace¶

GET /api/v1/secrets/sec_xyz789/rotation-config HTTP/1.1
Authorization: Bearer <token>

Vrátí aktuální konfiguraci rotace pro tajemství.

Aktualizovat konfiguraci rotace¶

PUT /api/v1/secrets/sec_xyz789/rotation-config HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Aktualizuje konfiguraci rotace (interval, povoleno/zakázáno, nastavení poskytovatele).

Spuštění rotace¶

POST /api/v1/secrets/sec_xyz789/rotate HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "id": "sec_xyz789",
  "version": 4,
  "rotated_at": "2026-02-10T17:00:00Z",
  "next_rotation": "2026-05-11T17:00:00Z"
}

Synchronizace¶

Získání stavu synchronizace¶

GET /api/v1/secrets/sec_xyz789/sync-status HTTP/1.1
Authorization: Bearer <token>

Odpověď `200 OK`¶

{
  "id": "sec_xyz789",
  "sync_enabled": true,
  "targets": [
    {
      "target_id": "dc_east",
      "status": "synced",
      "last_synced": "2026-02-10T17:00:00Z",
      "version": 3
    },
    {
      "target_id": "dc_west",
      "status": "pending",
      "last_synced": "2026-02-10T16:45:00Z",
      "version": 2
    }
  ]
}

Vynucení synchronizace¶

POST /api/v1/secrets/sec_xyz789/force-sync HTTP/1.1
Authorization: Bearer <token>

Vynucení synchronizace (pro prostředí)¶

POST /api/v1/secrets/sec_xyz789/environments/production/force-sync HTTP/1.1
Authorization: Bearer <token>

Vynutí synchronizaci pouze pro konkrétní prostředí.

Vazby tajemství¶

Tajemství mohou být provázána s externími integracemi (správci tajemství, cloudoví poskytovatelé) pro automatickou synchronizaci.

Výpis vazeb¶

GET /api/v1/secrets/sec_xyz789/links HTTP/1.1
Authorization: Bearer <token>

Vytvoření vazby¶

POST /api/v1/secrets/sec_xyz789/links HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Propojí tajemství s externím integračním cílem.

Smazání vazby¶

DELETE /api/v1/secrets/sec_xyz789/links/link_abc123 HTTP/1.1
Authorization: Bearer <token>

Požadovaná oprávnění¶

Operace	Požadované oprávnění
Vytvořit tajemství	`secret:write`
Číst tajemství (metadata)	`secret:read`
Číst tajemství (hodnota)	`secret:read`
Aktualizovat tajemství	`secret:write`
Smazat tajemství	`secret:delete`
Archivovat / obnovit	`secret:archive`
Trvalé smazání	`secret:permanent_delete`
Rotovat tajemství	`rotation:execute`
Spravovat konfiguraci rotace	`rotation:write`
Číst synchronizaci / vazby	`rotation:read`
Spravovat vazby	`rotation:write`
Vynutit synchronizaci	`secret:write`

Související¶

Začínáme — Autentizace a základní URL
API pro certifikáty — Správa certifikátů
Průvodce správou tajemství — Průvodce pro práci přes UI

API pro tajemství¶

Přehled endpointů¶

Vytvoření tajemství¶

Pole požadavku¶

Odpověď 201 Created¶

Výpis tajemství¶

Parametry dotazu¶

Odpověď 200 OK¶

Získání tajemství¶

Odpověď 200 OK¶

Aktualizace tajemství¶

Aktualizovatelná pole¶

Odpověď 200 OK¶

Smazání tajemství¶

Odpověď 204 No Content¶

Archivace a obnovení¶

Archivovat tajemství¶

Obnovit tajemství¶

Trvalé smazání¶

Kopírování tajemství¶

Verze tajemství¶

Výpis verzí¶

Odpověď 200 OK¶

Návrat k předchozí verzi¶

Rotace tajemství¶

Získat konfiguraci rotace¶

Aktualizovat konfiguraci rotace¶

Spuštění rotace¶

Odpověď 200 OK¶

Synchronizace¶

Získání stavu synchronizace¶

Odpověď 200 OK¶

Vynucení synchronizace¶

Vynucení synchronizace (pro prostředí)¶

Vazby tajemství¶

Výpis vazeb¶

Vytvoření vazby¶

Smazání vazby¶

Požadovaná oprávnění¶

Související¶

Odpověď `201 Created`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `204 No Content`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶

Odpověď `200 OK`¶