Gestionar les teves claus API
Troba la teva clau API a API i Webhooks a la consola, mantén-la al servidor, fes servir una aplicació sandbox separada per a les proves, i soluciona els errors 401 i 403.
API i Webhooks, limitat a l'aplicació que tens seleccionada. Una clau per aplicació, i la clau és l'entorn - no hi ha una clau de prova separada en una aplicació live. És un secret de servidor: mai en codi de frontend ni en un paquet d'aplicació.
La teva clau API es troba a API i Webhooks a la barra lateral de la consola, limitada a l'aplicació en què treballes. Tracta-la com una contrasenya: dona accés complet 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ó que vulguis des del desplegable a la part superior de la consola. Cada aplicació té la seva pròpia clau.
- Obre API i Webhooks
La teva clau API és aquí, al costat de les teves destinacions de webhook i els seus secrets de signatura.
- Create API key emet una clau nova; les claus són per aplicació.
- El secret es mostra aquí un sol cop - copia'l al teu propi magatzem de secrets.
- Rotate secret substitueix el secret sense canviar el nom de la clau.
- Last used és com distingeixes una clau viva d'una d'oblidada abans de revocar-la.
#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ó |
| Secret de signatura del webhook | Verificar que un webhook entrant realment ve de Didit | Per destinació |
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ó. Crea una aplicació separada en mode sandbox: les sessions de sandbox simulen totes les comprovacions externes, mai es facturen, i no toquen dades reals d'usuaris. Fes servir la seva clau mentre construeixes, i mantén una aplicació live separada per a les verificacions reals.
No existeix una "clau de prova" en una aplicació live. La clau és l'entorn, així que 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, torna a generar-la des de la mateixa pàgina API i Webhooks. Regenerar-la invalida la clau antiga immediatament, així que actualitza-la primer a tots els llocs on es fa servir - si no, el teu trànsit de producció comença a fallar en el moment que cliques el botó.
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, o s'ha regenerat | Copia la clau actual des de API i Webhooks per a aquesta aplicació. Comprova si hi ha espais en blanc o cometes de més, i 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 live (o al revés), un permís que li falta a la clau, 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 copia'n la clau en lloc de la teva. Detall complet: errors de l'API i què signifiquen.
#Restringir el que pot fer una clau
Si el que necessites és limitar a quines categories de dades pot arribar una clau, per exemple per evitar que un servei recuperi imatges de documents, això és una qüestió de permisos i no un ajust de la clau, i el que hi ha disponible depèn del teu compte. Pregunta-ho a suport en lloc de suposar que una clau no té restriccions o suposar que sí que en té; totes dues suposicions són arriscades en sentits oposats.
#Qui de l'equip pot veure les claus
La visibilitat de les claus segueix el rol. El rol Developer inclou les claus API; Reader no. 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 a Audit Logs atribuïdes a l'aplicació en lloc d'a una persona, que és exactament per què 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.