Autentifikácia

API TeamDay používa osobné prístupové tokeny (PAT) na autentifikáciu. Všetky požiadavky API musia obsahovať platný token v hlavičke Authorization.

Získanie vášho prístupového tokenu

Krok 1: Generovanie tokenu

  1. Prihláste sa na váš účet TeamDay na cc.teamday.ai
  2. Prejdite na Nastavenia → Prístup API
  3. Kliknutie na Generovať nový token
  4. Voliteľne nastavte vlastný čas vypršania (7-365 dní, predvolené: 90 dní)
  5. Skopírujte váš token okamžite - nebudete ho môcť vidieť znova!

Krok 2: Bezpečné uloženie

Váš token bude vyzerať takto:

td_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdE

Formát tokenu:

  • Predpona: td_ (identifikuje tokeny TeamDay)
  • Dĺžka: 43 alfanumerických znakov za predponou
  • Kódovanie: Base64url (bezpečný pre URL)

Uloženie v premenných prostredia:

# Unix/Linux/macOS
export TEAMDAY_TOKEN="td_your-actual-token-here"

# Windows (PowerShell)
$env:TEAMDAY_TOKEN="td_your-actual-token-here"

# Alebo v .env súbore (pre lokálny vývoj)
TEAMDAY_TOKEN=td_your-actual-token-here

Použitie vášho tokenu

Zahrňte váš token do hlavičky Authorization so schémou Bearer:

Authorization: Bearer td_your-actual-token-here

Príklady požiadaviek

Zoznam agentov:

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Vytvorenie agenta:

curl -X POST https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pomocník pre výskum",
    "role": "Výskum a analýza",
    "systemPrompt": "Ste užitočný pomocník pre výskum.",
    "visibility": "private"
  }'

Získanie podrobností vykonania:

curl https://cc.teamday.ai/api/v1/executions/exec_123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Funkcie bezpečnosti tokenov

Šifrovanie v kľudovom stave

Tokeny sú chránené bezpečnosťou na úrovni podniku:

  • Hashing: SHA-256 hash uložený v databáze (nezvratný)
  • Šifrovanie: Šifrovanie AES-256-GCM pre metadáta tokenu
  • Žiadne uloženie v čistom texte: Pôvodný token nikdy neuložený po vytvorení

Automatické overenie

Každá požiadavka API overuje:

  1. Formát tokenu - Správna predpona a dĺžka
  2. Vyhľadávanie hashu - Token existuje v databáze
  3. Vypršanie - Token nie je expirovaný
  4. Rozsah organizácie - Používateľ patrí do organizácie
  5. Sledovanie posledného použitia - Aktualizované pri každej požiadavke

Rozsah

Každý token je obmedzený na:

  • Používateľ: Token patrí špecifickému používateľovi (tvorca)
  • Organizácia: Dedí členstvo používateľa v organizácii
  • Povolenia: Používa rolu a povolenia používateľa

Dôležité: Tokeny dededia povolenia používateľa, ktorý ich vytvoril. Ak sa prístup používateľa odvolá, ich tokeny prestanú fungovať okamžite.

Správa tokenov

Zobrazenie aktívnych tokenov

Pozrite si všetky vaše aktívne tokeny v Nastaveniach → Prístup API:

  • Meno tokenu (voliteľný štítok)
  • Dátum vytvorenia
  • Časová pečiatka posledného použitia
  • Dátum vypršania
  • Rozsah povolení

Revokácia tokenov

Okamžitá revokácia tokenu:

  1. Prejdite na Nastavenia → Prístup API
  2. Nájdite token v zozname
  3. Kliknutie na Revokácia
  4. Potvrďte vymazanie

Kedy revokáciou:

  • Token kompromitovaný alebo zverejnený
  • Člen tímu opúšťa organizáciu
  • Token už nie je potrebný
  • Rotácia poverení (osvedčený postup bezpečnosti)

Vypršanie tokenu

Predvolené vypršanie: 90 dní

Vlastné vypršanie:

  • Minimum: 7 dní
  • Maximum: 365 dní

Čo sa stane po vypršaní:

  • Požiadavky API vrátia 401 Unauthorized
  • Chybová správa: "Token expired"
  • Token sa automaticky vyčistí (měkké vymazanie)

Automatické obnovenie: Nie je podporované. Pred vypršaním vygenerujte nový token.

Chybové odozvy

Chýbajúci token

Požiadavka:

curl https://cc.teamday.ai/api/v1/agents

Odozva:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Authorization header required"
}

Neplatný token

Požiadavka:

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer invalid_token"

Odozva:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or expired token"
}

Expirovaný token

Požiadavka:

curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer td_expired_token"

Odozva:

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Token expired"
}

Osvedčené postupy bezpečnosti

Áno ✅

  • Ukladajte tokeny v premenných prostredia - Nikdy nekódujte v zdroji
  • Používajte samostatné tokeny na integráciu - Jednoduchšie sledovanie a revokácia
  • Nastavte vhodné dátumy vypršania - Kratšie pre vysokoriziková prostredia
  • Rotujte tokeny pravidelne - Najmä pre produkčné systémy
  • Revokujte okamžite, ak boli kompromitované - Lepšie bezpečné ako okamihy
  • Používajte iba HTTPS - Nikdy neposielajte tokeny po obyčajnom HTTP
  • Monitorujte použitie tokenov - Pravidelne kontrolujte časové pečiatky "posledného použitia"

Nie ❌

  • Nikdy nepridávajte tokeny do Git - Používajte .gitignore pre .env súbory
  • Nikdy nezdieľajte tokeny - Každá integrácia by mala svoju
  • Nikdy neskratujte tokeny - Redakujte z protokolov aplikácie
  • Nikdy neposielajte v parametroch URL - Používajte iba hlavičky
  • Nikdy neveružívajte v rôznych prostrediach - Dev/staging/prod by mali mať samostatné tokeny
  • Nikdy neukladajte v kóde na strane klienta - Tokeny sú iba na strane servera

Príklad premenných prostredia

# .env (pridaj do .gitignore!)
TEAMDAY_TOKEN=td_your-actual-token-here

# Použitie v kóde
const token = process.env.TEAMDAY_TOKEN

const response = await fetch('https://cc.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
})

Stratégia rotácie tokenov

Odporúčaný rozvrh rotácie:

  • Vývoj: 90 dní (predvolene)
  • Staging: 60 dní
  • Produkcia: 30 dní
  • Vysoká bezpečnosť: 7 dní

Ako rotovať bez downtime:

  1. Generovať nový token (ešte nerevokujte starý)
  2. Aktualizovať aplikácie na používanie nového tokenu
  3. Nasadiť a overiť nový token funguje
  4. Monitorovať 24-48 hodín (skontrolujte použitie starého tokenu)
  5. Revokujte starý token po potvrdení nepoužitia

Obmedzenie frekvencie

Aktuálny stav: Žiadne limity frekvencie vynútené

Osvedčené postupy:

  • Implementujte exponenciálny backoff pre opakované pokusy
  • Ukladajte do cache odozvy, keď je to vhodné
  • Používajte rozumné frekvencie požiadaviek (< 100 req/min odporúčané)

Budúcnosť: Limity frekvencie sa môžu zaviesť. Poskytneme vopred upozornenie a dokumentáciu.

OAuth (Čoskoro)

Plánované funkcie:

  • Podpora OAuth 2.0 pre integrácie tretích strán
  • Tokeny s rozsahom (iba čítanie, zápis, admin)
  • Kľúče API na úrovni organizácie

Sledovať progres OAuth →

Testovanie vášho tokenu

Rýchly test:

# Mali by ste dostať zoznam agentov (alebo prázdne pole)
curl https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Príklad úspešnej odozvy
[
  {
    "id": "agent_123",
    "name": "Môj agent",
    "role": "Pomocník",
    "createdAt": "2025-12-09T12:00:00Z"
  }
]

Ak vidíte 401 Unauthorized:

  1. Overte, či bol token skopírovaný správne (bez extra medzier)
  2. Skontrolujte, či token nie je expirovaný v Nastaveniach → Prístup API
  3. Potvrďte, že používateľ má stále prístup k organizácii
  4. Skúste vygenerovať nový token

Potrebujete pomoc?

Token nefunguje?

  • Skontrolujte referenciu chýb na riešenie problémov
  • Overte formát: td_ + 43 znakov
  • Potvrďte, že nie je expirovaný v nástrojoch

Otázky?

Posledná aktualizácia: 9. december 2025