API pro tokeny¶

Evidence, sledování, obnova a nasazení externě vydaných API tokenů

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-10-22

Dostupnost funkce

Správa tokenů je dostupná od MazeVault v1.0.60 jako Enterprise funkce. Všechny níže uvedené endpointy jsou gatované licenční funkcí token_management (licence PoC a Enterprise). Bez ní API vrací 403 Forbidden. Viz Licencování a Průvodce správou tokenů.

Přehled endpointů¶

Metoda	Endpoint	Oprávnění	Popis
POST	`/api/v1/tokens`	`token:write`	Zaevidování spravovaného tokenu
GET	`/api/v1/tokens`	`token:read`	Seznam spravovaných tokenů
GET	`/api/v1/tokens/:id`	`token:read`	Detail tokenu podle ID (včetně cílů nasazení)
PUT	`/api/v1/tokens/:id`	`token:write`	Aktualizace metadat tokenu
DELETE	`/api/v1/tokens/:id`	`token:delete`	Smazání tokenu a jeho cílů nasazení
GET	`/api/v1/tokens/:id/value`	`token:admin`	Zobrazení uložené hodnoty tokenu
POST	`/api/v1/tokens/:id/renew`	`token:write`	Obnova hodnoty a exspirace tokenu
GET	`/api/v1/tokens/:id/targets`	`token:read`	Seznam cílů nasazení
POST	`/api/v1/tokens/:id/targets`	`token:write`	Přidání cíle nasazení
DELETE	`/api/v1/tokens/:id/targets/:targetId`	`token:write`	Odebrání cíle nasazení
POST	`/api/v1/tokens/:id/targets/:targetId/sync`	`token:write`	Okamžité nasazení aktuální hodnoty na cíl

Spravované tokeny jsou vázané na organizaci; organizace se bere z autentizované relace. Token patřící jiné organizaci je zodpovězen 404 Not Found.

Vytvoření tokenu¶

Zaeviduje externě vydaný token. Hodnota je okamžitě zašifrována (nebo v režimu Orchestrátora externě uložena) a endpointy seznamu ani detailu ji nikdy nevracejí.

POST /api/v1/tokens HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "name": "jira-automation-token",
  "description": "CI automation token for Jira Cloud",
  "provider": "jira",
  "value": "ATATT3xFfGF0...",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "expires_at": "2027-01-01T00:00:00Z",
  "lead_time_days": 30,
  "metadata": { "owner": "platform-team", "ticket": "OPS-1234" }
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`name`	string	✅	Unikátní název v rámci organizace/projektu
`description`	string	—	Účel tokenu
`provider`	string	—	Volný textový štítek vydávajícího systému (`jira`, `signi`, …)
`value`	string	✅	Tajná hodnota tokenu; pouze pro zápis
`project_id`	string (UUID)	—	Volitelná vazba na projekt; vyžadována pro nasazení na agenty a integrace projektu
`expires_at`	string (ISO 8601)	✅	Časové razítko exspirace podle zdrojového systému
`lead_time_days`	integer	—	Počet dní před exspirací, kdy se otevře incident `token_expiry` (výchozí `30`)
`metadata`	object	—	Volné páry klíč/hodnota

Odpověď `201 Created`¶

{
  "id": "00000000-0000-4000-8000-000000000001",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "jira-automation-token",
  "description": "CI automation token for Jira Cloud",
  "provider": "jira",
  "storage_mode": "local",
  "expires_at": "2027-01-01T00:00:00Z",
  "lead_time_days": 30,
  "status": "active",
  "is_expired": false,
  "days_until_expiry": 436,
  "metadata": { "owner": "platform-team", "ticket": "OPS-1234" },
  "created_by": "a1b2c3d4-0000-0000-0000-000000000001",
  "created_at": "2026-10-22T08:00:00Z",
  "updated_at": "2026-10-22T08:00:00Z"
}

Pole objektu tokenu¶

Pole	Popis
`storage_mode`	`local` (AES-256-GCM v databázi) nebo `external` (externě uloženo v režimu Orchestrátora)
`external_provider_type`	Přítomno, když je `storage_mode` `external`; identifikuje offload providera
`status`	`active`, `expired` nebo `revoked`
`is_expired`	`true`, jakmile `expires_at` uplynulo
`days_until_expiry`	Zbývající celé dny (záporné po exspiraci)
`last_renewed_at`, `renewal_notes`	Nastaveno operací obnovy
`deployment_targets`	Obsaženo pouze v odpovědi detailu

Seznam tokenů¶

GET /api/v1/tokens?status=active&provider=jira&page=1&limit=50 HTTP/1.1
Authorization: ******

Parametry dotazu¶

Parametr	Typ	Popis
`project_id`	UUID	Filtr podle projektu
`provider`	string	Filtr podle štítku providera
`status`	string	`active`, `expired` nebo `revoked`
`page`	integer	Číslo stránky (výchozí `1`)
`limit`	integer	Velikost stránky, max. `200`

Odpověď `200 OK`¶

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "name": "jira-automation-token",
      "provider": "jira",
      "storage_mode": "local",
      "expires_at": "2027-01-01T00:00:00Z",
      "lead_time_days": 30,
      "status": "active",
      "is_expired": false,
      "days_until_expiry": 436,
      "created_at": "2026-10-22T08:00:00Z",
      "updated_at": "2026-10-22T08:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

Získání tokenu¶

GET /api/v1/tokens/00000000-0000-4000-8000-000000000001 HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

Vrací objekt tokenu včetně pole deployment_targets (viz Objekt cíle nasazení).

Aktualizace tokenu¶

Aktualizuje pouze metadata. Hodnotu tokenu lze změnit výhradně přes Obnovu tokenu.

PUT /api/v1/tokens/00000000-0000-4000-8000-000000000001 HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "description": "CI automation token for Jira Cloud (shared with release pipeline)",
  "lead_time_days": 45,
  "status": "active"
}

Pole požadavku¶

Pole	Typ	Popis
`name`	string	Nový název (musí zůstat unikátní)
`description`	string	Nový popis
`provider`	string	Nový štítek providera
`expires_at`	string (ISO 8601)	Opravené časové razítko exspirace
`lead_time_days`	integer	Nový lead time upozornění
`status`	string	`active` nebo `revoked`
`metadata`	object	Nahradí mapu metadat

Všechna pole jsou volitelná; vynechaná pole zůstávají beze změny.

Odpověď `200 OK`¶

Vrací aktualizovaný objekt tokenu.

Smazání tokenu¶

Smaže token a všechny jeho cíle nasazení. V režimu Orchestrátora je odstraněna i externě uložená hodnota.

DELETE /api/v1/tokens/00000000-0000-4000-8000-000000000001 HTTP/1.1
Authorization: ******

Odpověď `204 No Content`¶

Zobrazení hodnoty tokenu¶

Vrací dešifrovanou (nebo externě načtenou) hodnotu. Vyžaduje token:admin a je zaznamenáno v audit logu jako TOKEN_REVEAL.

GET /api/v1/tokens/00000000-0000-4000-8000-000000000001/value HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

{
  "value": "ATATT3xFfGF0..."
}

Obnova tokenu¶

Zaznamená hodnotu získanou ručně ve zdrojovém systému spolu s novou exspirací. Vyřeší otevřený incident token_expiry, vrátí stav na active a znovu nasadí každý cíl se sync_on_renewal: true.

POST /api/v1/tokens/00000000-0000-4000-8000-000000000001/renew HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "value": "ATATT3xFfGF0-new...",
  "expires_at": "2028-01-01T00:00:00Z",
  "renewal_notes": "Regenerated in Jira by ops on OPS-1301"
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`value`	string	✅	Nová tajná hodnota tokenu
`expires_at`	string (ISO 8601)	✅	Nové časové razítko exspirace
`renewal_notes`	string	—	Volná poznámka uložená u tokenu

Odpověď `200 OK`¶

Vrací aktualizovaný objekt tokenu s vyplněnými last_renewed_at a renewal_notes.

Seznam cílů nasazení¶

GET /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

[
  {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "token_id": "00000000-0000-4000-8000-000000000001",
    "target_type": "agent_file",
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target_path": "/etc/jira-sync/config.json",
    "file_format": "json",
    "secret_key": "jira.api_token",
    "post_install_cmd": "systemctl restart jira-sync",
    "backup": true,
    "sync_on_renewal": true,
    "deployment_status": "deployed",
    "last_sync_at": "2026-10-22T08:05:00Z",
    "last_sync_status": "success"
  }
]

Přidání cíle nasazení¶

POST /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets HTTP/1.1
Authorization: ******
Content-Type: application/json

{
  "target_type": "kubernetes_secret",
  "integration_id": "9b2c1a7e-1111-2222-3333-444455556666",
  "config": {
    "namespace": "integrations",
    "secret_name": "jira-credentials",
    "key_name": "api-token"
  },
  "sync_on_renewal": true
}

Pole požadavku¶

Pole	Typ	Povinné	Popis
`target_type`	string	—	`agent_file` (výchozí), `kubernetes_secret`, `azure_keyvault`, `aws_secrets_manager`
`integration_id`	string (UUID)	dle typu	Integrace použitá pro neagentní cíle
`config`	object	dle typu	Konfigurace specifická pro typ (viz níže)
`agent_id`	string (UUID)	`agent_file`	Agent, který spravuje cílový soubor
`target_path`	string	`agent_file`	Absolutní cesta ke konfiguračnímu souboru
`file_format`	string	—	`json`, `yaml` nebo `env` (výchozí `env`)
`secret_key`	string	`agent_file`	Klíč, pod kterým je hodnota zapsána (tečková notace pro vnořené klíče JSON/YAML)
`post_install_cmd`	string	—	Příkaz spuštěný agentem po úspěšném zápisu; musí odpovídat allowlistu příkazů agenta
`backup`	boolean	—	Uchovat kopii předchozího souboru s časovým razítkem
`sync_on_renewal`	boolean	—	Automaticky znovu nasadit po každé obnově

Požadovaná konfigurace podle typu cíle¶

`target_type`	Povinná pole
`agent_file`	`agent_id`, `target_path`, `secret_key`
`kubernetes_secret`	`config.namespace`, `config.secret_name`, `config.key_name`
`azure_keyvault`	`integration_id`, `config.secret_name`
`aws_secrets_manager`	`integration_id`, `config.secret_id`, `config.region`

Odpověď `201 Created`¶

Vrací vytvořený Objekt cíle nasazení s deployment_status: pending.

Odebrání cíle nasazení¶

DELETE /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets/0f8fad5b-d9cb-469f-a165-70867728950e HTTP/1.1
Authorization: ******

Odpověď `204 No Content`¶

Synchronizace cíle nasazení¶

Okamžitě odešle aktuální hodnotu tokenu na cíl. Použijte po přidání cíle nebo pro zopakování neúspěšného nasazení.

POST /api/v1/tokens/00000000-0000-4000-8000-000000000001/targets/0f8fad5b-d9cb-469f-a165-70867728950e/sync HTTP/1.1
Authorization: ******

Odpověď `200 OK`¶

Vrací aktualizovaný objekt cíle nasazení s deployment_status, last_sync_at, last_sync_status a — při selhání — error_message.

Objekt cíle nasazení¶

Pole	Popis
`id`, `token_id`	Identifikátory
`target_type`	`agent_file`, `kubernetes_secret`, `azure_keyvault`, `aws_secrets_manager`
`agent_id`, `integration_id`, `config`	Adresace cíle (závisí na typu)
`target_path`, `file_format`, `secret_key`, `post_install_cmd`, `backup`	Volby souboru agenta
`sync_on_renewal`	Znovu nasadit po obnově
`deployment_status`	`pending`, `deployed` nebo `failed`
`last_sync_at`, `last_sync_status`, `error_message`	Výsledek posledního nasazení

Chybové odpovědi¶

Všechny endpointy používají standardní chybové odpovědi MazeVaultu:

HTTP status	Význam
`400 Bad Request`	Neplatné tělo, chybějící `name` / `value` / `expires_at`, nepodporovaný `target_type` nebo chybějící konfigurace specifická pro typ cíle
`401 Unauthorized`	Chybějící nebo neplatný bearer token
`403 Forbidden`	Nedostatečné oprávnění, nebo licenční funkce `token_management` není dostupná
`404 Not Found`	Token nebo cíl nasazení v organizaci volajícího neexistuje
`409 Conflict`	Token se stejným názvem již v daném rozsahu existuje
`503 Service Unavailable`	Režim Orchestrátora je aktivní, ale není nakonfigurován žádný offload provider

Související¶

📖 Průvodce správou tokenů
📖 Terraform Provider — mazevault_token
📖 Notifikace a upozornění
🔐 RBAC role a oprávnění
📖 Audit log

API pro tokeny¶

Přehled endpointů¶

Vytvoření tokenu¶

Pole požadavku¶

Odpověď 201 Created¶

Pole objektu tokenu¶

Seznam tokenů¶

Parametry dotazu¶

Odpověď 200 OK¶

Získání tokenu¶

Odpověď 200 OK¶

Aktualizace tokenu¶

Pole požadavku¶

Odpověď 200 OK¶

Smazání tokenu¶

Odpověď 204 No Content¶

Zobrazení hodnoty tokenu¶

Odpověď 200 OK¶

Obnova tokenu¶

Pole požadavku¶

Odpověď 200 OK¶

Seznam cílů nasazení¶

Odpověď 200 OK¶

Přidání cíle nasazení¶

Pole požadavku¶

Požadovaná konfigurace podle typu cíle¶

Odpověď 201 Created¶

Odebrání cíle nasazení¶

Odpověď 204 No Content¶

Synchronizace cíle nasazení¶

Odpověď 200 OK¶

Objekt cíle nasazení¶

Chybové odpovědi¶

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`¶

Odpověď `201 Created`¶

Odpověď `204 No Content`¶

Odpověď `200 OK`¶