Autenticación
Token bearer
Envía Authorization: Bearer sk_live_… en cada solicitud. Nunca pongas una clave en una URL ni en una cookie; no hay otra cabecera para ella. Una clave ausente, mal formada, revocada o caducada responde 401 unauthorized, sin indicar cuál es el caso.
Una clave pertenece a un espacio de trabajo. GET /v1/workspaces/current lo devuelve junto con su plan. Si envías X-Workspace-Id, debe nombrar el espacio de trabajo de la clave.
Crear claves
Crea claves en la app, en Settings → API. Los editores, los administradores y el propietario crean claves que actúan como ellos mismos; los administradores también pueden renombrar y revocar las de cualquiera. Los lectores no pueden crear claves. Un espacio de trabajo puede tener 50 claves activas.
El secreto se muestra una sola vez y solo guardamos su hash. La API no admite llamadas desde navegadores de otros orígenes: mantén las claves en tu servidor.
Scopes
Elige los scopes al crear la clave; no se pueden cambiar después (renueva la clave o crea una nueva). Una solicitud necesita el scope de la ruta, que aparece junto a cada ruta en la referencia de la API. Una clave sin él recibe 403 forbidden con details.reason missing_scope.
codes:readLista y lee códigos, sus versiones y su actividad; descarga archivos; inicia y consulta exportaciones y tandas en lote.Viewer o superiorcodes:writeCrea, cambia, pausa, mueve y elimina códigos; creación en lote; sube logotipos y archivos.Editor o superioranalytics:readEstadísticas del espacio de trabajo y de cada código, y registros por escaneo.Viewer o superiorsubmissions:readRespuestas a formularios alojados. Contienen datos personales de quienes responden.Editor o superiorfolders:readLista y lee carpetas.Viewer o superiorfolders:writeCrea, renombra, mueve y elimina carpetas. Compartir se queda en la app.Editor o superiortemplates:readLista y lee plantillas de diseño.Viewer o superiortemplates:writeCrea, cambia y elimina plantillas de diseño.Editor o superiordomains:readLista los dominios personalizados y su estado, para elegir uno para códigos nuevos.Viewer o superiorwebhooks:readLista los endpoints de webhook y sus entregas.Admin o superiorwebhooks:writeRegistra, cambia y elimina endpoints de webhook; envía un evento de prueba; reenvía entregas. Solo administradores.Admin o superiortags:readLista las etiquetas del espacio de trabajo y cuántos códigos lleva cada una.Viewer o superiortags:writeCrea, renombra, cambia el color y elimina etiquetas. Etiquetar códigos requiere Codes · write.Editor o superiorcards:readLista y lee las tarjetas de visita del equipo y sus estadísticas.Viewer o superiorcards:writeCrea, cambia, desactiva y reasigna tarjetas de visita. Solo administradores.Admin o superiorconversions:writeEnvía conversiones desde tu servidor (pedidos, registros) para el embudo de escaneos.Editor o superiorRoles
Una clave nunca hace más de lo que permite el rol actual de quien la creó, con un tope de Editor. Si a quien la creó lo pasan a Viewer, la clave pierde sus scopes de escritura al instante; cuando quien la creó deja el espacio de trabajo, sus claves se revocan.
webhooks:read y webhooks:write son la excepción: solo los administradores y el propietario pueden concederlos, y siguen funcionando solo mientras quien los creó siga siendo administrador.
Restricciones de carpeta y de IP
Una clave puede limitarse a hasta 20 carpetas y sus subcarpetas, por ejemplo una clave por carpeta de cliente. Entonces no ve nada fuera de ellas, y una escritura en otro sitio responde 403 con details.reason api_key_folder_restricted.
Una clave también puede limitarse a hasta 20 rangos de IP en forma CIDR (203.0.113.0/24). Una llamada desde cualquier otro lugar responde 403 con details.reason ip_not_allowed.
Caducidad y renovación
Una clave puede caducar en una fecha que elijas. Renovar una clave emite un secreto nuevo con el mismo nombre, scopes y restricciones; el secreto antiguo sigue funcionando 24 horas por defecto (de 0 a 168), para que puedas desplegar el nuevo sin interrupciones. Revocar surte efecto de inmediato.
Lo que una clave no puede hacer
Las claves solo llaman a las rutas de la referencia de la API. Tu cuenta, los miembros y las invitaciones, la facturación, los ajustes del espacio de trabajo, el uso compartido, la configuración de dominios y las propias claves de API se quedan en la app: esas rutas responden a una clave con 403 forbidden y details.reason session_required.