Crea claus API a Desenvolupadors, Claus d'API, una per servei amb l'accés que necessita, guarda-les al servidor, roda-les i resol els errors 401 i 403.
Desenvolupadors → Claus d'API, limitat a l'aplicació que tens seleccionada. Cada aplicació té una clau Principal, i en pots crear més, una per servei, cadascuna amb el seu propi accés i la seva caducitat. Una clau és un secret de servidor: mai en codi de frontend ni en un paquet d'aplicació.
Les teves claus API es troben a Desenvolupadors → Claus d'API a la consola, limitades a l'aplicació en què treballes. Tracta cada clau com una contrasenya: dona accés a l'API en nom d'aquesta aplicació.
#Trobar la teva clau
- Inicia sessió a la Business Console
Ves a business.didit.me i inicia sessió.
- Selecciona la teva aplicació
Tria l'aplicació des de la targeta d'aplicació a la part superior de la barra lateral. Cada aplicació té les seves pròpies claus.
- Obre Desenvolupadors i després Claus d'API
La pestanya Claus mostra totes les claus, començant per la clau Principal, amb el seu accés, quan es va fer servir per últim cop i quan caduca.
#Crear una clau
Dona a cada servei que crida Didit la seva pròpia clau, perquè puguis veure què fa cadascuna i revocar-la per separat.
- Prem Crea una clau
A Desenvolupadors → Claus d'API.
- Posa-li un nom i tria l'entorn
Anomena la clau segons el servei que la farà servir, tria Producció (verificacions reals, facturades) o Sandbox (dades de prova, mai facturades; la clau es crea a l'aplicació Sandbox de la teva organització), i tria quan caduca: mai, al cap de 30 dies, 90 dies o un any, o en una data que triïs.
- Tria el seu accés
Accés total llegeix i escriu tot, per al teu propi backend. Només lectura veu sessions, decisions i mitjans però no pot canviar res, per a un soci que només necessita resultats. Personalitzat et deixa triar, recurs per recurs. Desmarca Inclou els mitjans quan el servei només necessiti la decisió, no imatges de documents, selfies, vídeos ni informes en PDF.
- Revisa i copia el secret
El secret complet es mostra un sol cop, quan es crea la clau. Copia'l directament al teu gestor de secrets.
La clau Principal és el secret original de l'aplicació. Sempre té accés total i es pot rotar però no revocar.
#La clau API i el secret de signatura són coses diferents
Val la pena dir-ho clarament, perquè confondre'ls produeix errors confusos:
| Per a què serveix | On | |
|---|---|---|
| Clau API | Autenticar les teves crides a Didit, a la capçalera x-api-key | Per aplicació, tantes com en necessitis |
| Secret de signatura del webhook | Verificar que un webhook entrant realment ve de Didit | Per endpoint de webhook |
Enviar el secret de signatura com si fos la teva clau API produeix un 401. Verificar un webhook amb la teva clau API produeix una discrepància de signatura. Totes dues coses són habituals.
La teva clau API és un secret. No la posis mai en codi de frontend, en un repositori públic ni en un paquet d'aplicació mòbil - manté-la només al servidor. Una clau dins d'un paquet d'aplicació publicat és una clau que ja té un atacant. Consulta autenticació de l'API.
#Aconseguir una clau per fer proves
No proves contra producció. Canvia la consola a Sandbox i crea-hi una clau, o tria Sandbox com a entorn quan en creïs una. Les sessions de sandbox simulen totes les comprovacions externes, mai es facturen, i no toquen dades reals d'usuaris.
Una clau pertany a una aplicació, i amb ella a l'entorn d'aquesta aplicació: una clau de sandbox mai crea una verificació real, i una clau de producció mai en crea una de sandbox. Val la pena anomenar les teves claus sense ambigüitat allà on guardis els teus secrets. Consulta provar en sandbox.
#Rotar la teva clau
Si una clau pot haver-se exposat, obre-la i tria Rota la clau. Obtens un secret nou, i l'antic continua funcionant durant 24 hores, perquè puguis desplegar el secret nou sense temps d'inactivitat. Després d'això, qualsevol petició amb el secret antic retorna un 401.
Si una clau ha de deixar de funcionar ara mateix, fes servir Revoca la clau. Revocar-la l'atura a l'instant i no es pot desfer. La clau Principal només es pot rotar.
Rotar-la de manera programada és bona pràctica. Planifica-ho com un desplegament, no com un clic.
#Solucionar el 401 i el 403
| Error | Causa | Solució |
|---|---|---|
401 | La clau falta, és mal formada, ha caducat, s'ha revocat, o es va rotar fa més de 24 hores | Comprova la clau a Desenvolupadors → Claus d'API per a aquesta aplicació. Busca espais en blanc o cometes de més, i comprova que no hagis enganxat un secret de signatura |
403 | La clau és vàlida però aquesta crida no està permesa | Normalment és l'aplicació equivocada, un camp només de sandbox en una clau de producció (o al revés), un accés que no s'ha donat a la clau (per exemple, una clau de només lectura que intenta escriure), o una funció no activada al teu compte |
Un 403 en un flux de treball concret gairebé sempre vol dir que la clau pertany a una aplicació diferent de la que és propietària d'aquest flux de treball. Canvia d'aplicació a la consola i fes servir una de les seves claus. Detall complet: errors de l'API i què signifiquen.
#Restringir el que pot fer una clau
Tria l'accés quan creïs la clau, i canvia'l més endavant amb Edita l'accés (el secret continua sent el mateix; l'accés de la clau Principal no es pot editar). Només lectura impedeix que un soci canviï res, Personalitzat defineix Cap, Lectura o Escriptura per recurs (sessions, decisions, mitjans, persones, empreses i més), i deixar Inclou els mitjans desactivat impedeix que un servei descarregui imatges de documents, selfies, vídeos i informes en PDF. A Límits, una clau també es pot restringir a alguns fluxos de treball, només a sessions aprovades o a una llista d'adreces IP: una petició des de fora de la llista respon 403, i una sessió fora dels fluxos de treball o estats de la clau respon 404. Obre una clau per veure exactament què pot fer; una clau mai no pot fer més del que el seu accés permet.
#Qui de l'equip pot veure les claus
La visibilitat de les claus segueix el rol: per veure la pàgina cal el permís de llegir claus API, que el rol Desenvolupador inclou. Els secrets queden emmascarats a la consola. Si un company d'equip no troba la pàgina, comprova el seu rol abans de reportar-ho. Consulta convidar membres de l'equip i assignar rols.
#Cada crida queda registrada
Les peticions amb clau API apareixen al Registre d'auditoria atribuïdes a la clau en lloc d'a una persona. Per això mateix una clau compartida entre diversos serveis fa que un incident sigui més difícil d'investigar: una clau per consumidor és més fàcil de raonar. Consulta fer servir els registres d'auditoria.
Encara estàs encallat? Parla amb una persona.
Inclou l'ID de la teva organització i l'ID de la sessió sobre la qual preguntes.