Com compartir claus d'API de manera segura

No enganxeu mai una clau d'API en un xat o en un correu. Envieu-la amb un enllaç secret d'un sol ús: la clau es xifra al vostre navegador, la clau de desxifratge es queda a la part de l'enllaç que va després del # i la còpia desada es destrueix la primera vegada que s'obre. Després, roteu qualsevol clau que ja s'hagi enganxat sense xifrar.

La resta de la guia entra en el detall: per què fallen els canals de sempre, el procediment exacte del lliurament, què cal fer quan una clau es filtra igualment i els casos en què un enllaç d'un sol ús no és l'eina adequada.

Per què no és segur enviar una clau d'API per Slack o per correu?

Perquè tots dos conserven el missatge mentre algun sistema el retingui, i pel camí en fan còpies a cada dispositiu i a cada exportació.

• Tots dos permeten cercar-hi per sempre. Una clau compartida el 2023 pot ser l'origen del vostre proper incident. Els atacants que entren en un xat o en una bústia d'una empresa hi cerquen sistemàticament les cadenes que tenen aspecte de clau d'API: sk_live, AKIA, ghp_, Bearer.
• Tots dos se sincronitzen a tot arreu. Mòbils, portàtils personals, tauletes: dispositius que queden fora dels vostres controls de seguretat i fora de l'abast de la vostra política d'esborrat remot.
• Tots dos s'exporten. Les revisions de compliment normatiu, els requeriments judicials i les exportacions de l'espai de treball generen còpies de l'historial. Cada exportació és un altre lloc on viu la clau.
• Tots dos sobreviuen a la baixa d'una persona. El contracte del col·laborador extern s'acaba; el fil de missatges directes amb la vostra clau de Stripe, no.

Posar un secret en qualsevol de les dues eines vol dir acceptar que el secret viurà allà on acabi el missatge, mentre algun sistema el conservi. Cap dels dos no es va dissenyar per oblidar.

Abans de compartir-la: reduïu la clau

El millor lliurament és aquell en què la clau que es lliura gairebé no importa. Abans de generar res, apliqueu el mínim privilegi a l'origen:

• Limiteu-ne l'abast. Les claus restringides de Stripe, els testimonis d'accés personal de granularitat fina de GitHub i les polítiques d'AWS IAM limitades a accions i recursos concrets permeten el mateix: la majoria de proveïdors seriosos us deixen crear una clau que només pot fer l'única cosa que necessita el destinatari.
• Trieu accés només de lectura tret que l'escriptura sigui realment necessària.
• Definiu una caducitat al proveïdor quan la plataforma ho admeti (els PAT de granularitat fina de GitHub, les credencials temporals d'AWS mitjançant STS). Així, fins i tot una clau filtrada té una vida limitada, independentment del que feu després.
• Poseu-li el nom del destinatari (vendor-x-readonly) perquè, d'aquí a sis mesos, revocar-la sigui una decisió d'un cop d'ull i no una feina d'arqueologia.

Amb una clau d'abast limitat, que caduca i només de lectura, la pitjor filtració possible deixa de ser un incident i es queda en una molèstia.

El procediment del lliurament

1. Genereu la clau al sistema d'origen (AWS, Stripe, la vostra pròpia API) amb l'abast mínim, com s'explica més amunt.
2. Enganxeu-la en un enllaç secret d'un sol ús amb l'opció de destruir després de la lectura activada i la caducitat més curta que encaixi: 1 hora és l'opció predefinida més curta, després venen 24 hores i 7 dies, i amb el pla Pro podeu triar una data i una hora concretes. Prou temps per al lliurament real, i prou.
3. Afegiu-hi una frase de contrasenya i envieu-la per un altre canal: l'enllaç per correu i la frase per SMS o per missatge directe de Slack. A LinkPilot, la frase de contrasenya, la caducitat personalitzada i la cronologia d'auditoria són funcions del pla Pro, a 29 $ al mes. Si es filtra un dels dos canals, l'atacant només té mig trencaclosques. (LinkPilot calcula el hash de la frase de contrasenya al navegador amb SHA-256 abans d'enviar-la; la frase original no arriba mai a la base de dades ni als registres del servidor, i els intents es limiten a 5 per IP per minut.)
4. Envieu l'enllaç.
5. Confirmeu per un altre canal que el destinatari l'ha obert i reviseu la cronologia d'auditoria: una visualització, a l'hora prevista, des del lloc previst. Aquest és el vostre justificant.

Si l'enllaç arriba a la caducitat sense que ningú l'obri, revoqueu-lo i torneu-lo a enviar. No n'allargueu la caducitat ni el reaprofiteu.

Exemple: passar una clau restringida de Stripe

# generate a restricted key with the minimum needed scopes
stripe api_keys create \
  --restricted \
  --display-name "vendor-x-readonly"

# pipe the resulting key into a LinkPilot secret
curl -X POST https://api.uselinkpilot.com/v1/secrets \
  -H "Authorization: Bearer $LP_KEY" \
  -d 'payload=sk_restricted_…' \
  -d 'expires_in=3600' \
  -d 'burn_after_read=true'

Això és el que veu el destinatari: quan obre l'enllaç, apareix una pàgina amb el botó per mostrar el contingut, no la clau. Els previsualitzadors d'enllaços i els escàners de correu que carreguen l'URL per avançat només reben metadades, perquè una visualització només es registra amb l'acció explícita de mostrar el contingut, mai amb el GET. Quan el destinatari fa clic a «Mostra» (i introdueix la frase de contrasenya, si n'hi ha), veu la clau una sola vegada. Després, el contingut desat se sobreescriu i l'enllaç retorna un HTTP 410. Encara que el correu circuli per tota l'empresa, només la primera persona que l'obri l'haurà pogut llegir, i el registre d'auditoria us diu qui va ser.

Quin canal per a cada lliurament

Què heu de fer si es filtra una clau d'API?

Doneu-la per compromesa i roteu-la al proveïdor; suprimir el missatge no serveix de res. Compta qualsevol clau que hagi passat per un missatge de xat, el cos d'un correu, una captura de pantalla, un commit de git o un text publicat. Per ordre:

1. Emeteu primer la clau de substitució, si el proveïdor permet dues claus actives alhora. Així evitareu interrupcions per als usos legítims.
2. Revoqueu la clau filtrada al proveïdor. És l'únic pas que posa fi a l'exposició; suprimir el missatge de Slack no ho fa.
3. Lliureu la clau nova com cal: enllaç d'un sol ús, frase de contrasenya i caducitat curta, segons el procediment de més amunt.
4. Consulteu els registres d'ús del proveïdor per a la clau filtrada entre l'exposició i la revocació. Si hi ha crides inesperades, ja no és una neteja, és un incident.
5. Corregiu l'origen del problema: afegiu el secret a les eines d'env que exclou el vostre .gitignore, activeu la detecció de secrets al servei que allotja el repositori o actualitzeu el manual de procediments que deia a algú que l'enviés per missatge directe.

Tot el cicle hauria de durar uns minuts. Si rotar una clau fa prou por perquè la gent ho eviti, aquesta fragilitat és la vulnerabilitat real: corregiu-la primer.

Què heu d'evitar

• Tornar a enviar el mateix secret. Roteu-lo. Si el torneu a enviar, perdeu la garantia d'auditoria d'«una sola exposició» que feia útil l'enllaç d'un sol ús.
• Caducitats llargues. Trieu-les curtes per defecte. La majoria de lliuraments s'acaben en minuts; una finestra de 8 hores només és una filtració més llarga.
• Saltar-se la frase de contrasenya. No costa gairebé res i protegeix contra filtracions accidentals de l'URL: correus reenviats, pantalles compartides, algú que mira per sobre l'espatlla.
• Captures de pantalla de claus. Acaben al rodet de la càmera, a la sincronització de fotos al núvol i a la cerca d'imatges. Una captura té la mateixa permanència que enganxar la clau en un xat, però a qui l'ha feta li costa més trobar-la, mentre que un OCR la llegeix sense problema.
• Fer servir l'eina d'enllaços com a emmagatzematge. L'enllaç és el missatger, no la caixa forta. El destinatari ha de desar la clau en un gestor de contrasenyes o a les eines d'env tan bon punt la rebi.

Quan un enllaç d'un sol ús no és l'eina adequada

Una secció de franquesa: aquest procediment té límits.

• Les credencials entre màquines van en un gestor de secrets o al magatzem propi de la plataforma, i s'injecten en el desplegament o en temps d'execució. Una persona fent clic a un enllaç no és un pas de desplegament.
• Les credencials compartides de llarga durada van en un gestor de contrasenyes amb control d'accés real i revocació per persona.
• La rotació d'alta freqüència (claus que canvien cada hora) s'ha d'automatitzar de cap a cap; ni les persones ni els enllaços hi han de ser.
• Els secrets que no us podeu permetre que toqui cap tercer: feu el lliurament fora de línia. Actualització del 29 de setembre de 2026: aquest punt deia originalment que LinkPilot no oferia E2EE i que calia fer servir una eina amb xifratge d'extrem a extrem. Ara LinkPilot xifra el text al navegador, de manera que només desa text xifrat, i també els fitxers adjunts que l'acompanyen. La pàgina d'Arquitectura de seguretat explica exactament què està protegit i què no.

Per al cas habitual, una persona que lliura una credencial a una altra persona una sola vegada, l'enllaç d'un sol ús amb frase de contrasenya i caducitat curta és el procediment senzill més sòlid que hi ha.

Lectures relacionades

• Per què els URL filtren informació confidencial
• Compartir contrasenyes de manera segura: comparativa de 5 mètodes
• Arquitectura de seguretat de LinkPilot
• Comparativa d'API d'escurçadors d'URL
• Generador gratuït d'enllaços secrets

Referències

• Stripe Docs, API keys: limit access with restricted keys.
• GitHub Docs, Managing your personal access tokens.
• AWS IAM User Guide, Temporary security credentials in IAM.