Les claus d'API permeten que scripts, serveis i integracions externes iniciïn sessió a Yellow sense que hi hagi una persona al mig. Aquesta guia és per a propietaris d'organització que emeten claus al seu equip o a comptes de servei. Per a claus propietat de l'usuari (les teves, lligades al teu compte), vegeu El teu perfil i configuració.

Què és una clau d'API

Una clau d'API és una cadena llarga i opaca que autentica una petició com a un actor concret de la plataforma. L'actor pot ser:

  • Un usuari — la clau actua en nom d'aquest usuari. Veu el que veu l'usuari, pot fer el que pot fer l'usuari.
  • Un compte de servei — un actor no humà creat específicament per a automatització. Té la seva pròpia membresia en una organització i les seves pròpies assignacions de rols, separades de qualsevol persona real.

Els comptes de servei són la forma recomanada per a integracions: quan l'enginyer que va muntar la integració se'n va, la clau continua funcionant perquè no depèn d'un compte personal.

Emetre una clau

Des de la pàgina de l'organització → Claus d'API → + Nova clau:

  1. Propietari — l'usuari o compte de servei amb què s'autentica la clau.
  2. Nom — el que vols recordar ("Webhook de Stripe", "Informe nocturn").
  3. Abast — quins entorns i capacitats pot tocar la clau. Sovint més estret que els permisos complets del propietari, perquè la clau només faci la feina per a què es va emetre.
  4. Caducitat (opcional) — una data després de la qual la clau deixa de funcionar. Recomanat per a integracions de curta durada.
  5. Desa.

El valor de la clau es mostra una sola vegada, en emetre-la. Copia'l immediatament al gestor de secrets del sistema consumidor. Yellow no guarda el valor en clar — si el perds, has de rotar a una clau nova.

Capacitats i abast

Una clau no pot fer més del que pot el seu propietari. Si el propietari és un compte de servei amb el rol Editor de vendes sobre l'esquema CRM, la clau només pot editar dades del CRM. Emetre una clau no eleva permisos — primer concedeixes capacitats al propietari, després emets la clau.

Per a claus amb privilegis mínims, crea un compte de servei dedicat per a cada integració, dona-li només els rols que necessita la integració, i després emet la clau.

Rotar una clau

Quan rotes una clau, Yellow emet un valor nou i invalida l'antic immediatament. Des de la fila de la clau, fes clic a Rota, copia el nou valor, actualitza el sistema consumidor.

Rota de manera proactiva:

  • Cada 90 dies per a qualsevol clau que toqui producció, com a higiene bàsica.
  • Immediatament si sospites d'una fuita (la clau era en un commit públic, en una pantalla compartida, en un portàtil antic).
  • Quan un membre de l'equip que coneixia el valor se'n va.

Revocar una clau

Revoca mata una clau permanentment. El sistema consumidor comença a fallar a la pròxima petició — no hi ha període de gràcia. Fes servir la revocació per a claus d'un sol ús que han complert el seu propòsit, o per a claus compromeses quan la rotació no és suficient.

Auditar l'ús d'una clau

Cada clau porta metadades que pots inspeccionar:

  • Últim ús — la petició amb èxit més recent.
  • Emissor — qui va crear la clau.
  • Actor propietari — qui actua com la clau.

Les claus inactives molt de temps (últim ús fa mesos, sense propòsit aparent) són bones candidates a rotació o revocació. Yellow no les elimina automàticament.

Llista de comprovació de seguretat

  • Emet una clau per integració; mai compartis una entre consumidors.
  • Fes servir comptes de servei, no usuaris personals, per a automatització.
  • Posa caducitat a les claus de curta durada.
  • Guarda les claus només en un gestor de secrets — mai al control de versions, mai en documents compartits.
  • Revoca les claus dels membres que se'n van el mateix dia.

Relacionats