- El App ID y el Organization ID son identificadores públicos, seguros para usar en código del lado del cliente e inicialización del SDK.
- La Clave API de app y la Clave API de organización son secretos privados. Almacénalas de forma segura y nunca las expongas en código del lado del cliente.
App ID
El App ID es un UUID (v4) público que identifica tu app de OneSignal. Lo usas para:- Inicializar el SDK (configuración del SDK móvil, configuración del SDK web)
- Realizar solicitudes a la API como Crear mensaje y Crear usuario
Tu App ID es seguro para usar en la inicialización del SDK del lado del cliente. No es un secreto.
Organization ID
El Organization ID (Org ID) es un UUID (v4) que agrupa todas las apps bajo tu plan de facturación. Lo necesitas para APIs a nivel de organización como: Encuéntralo en Organizations > Tu organización > Keys & IDs o a través de la API de Ver una app.
Claves API
Hay dos tipos de claves API. Ambas autentican solicitudes a la REST API y deben mantenerse en secreto. Elige la que coincida con lo que quieres hacer:| Clave | Para qué se usa |
|---|---|
| Clave API de app | Una app específica: enviar mensajes, crear usuarios, leer estadísticas. |
| Clave API de organización | En toda tu organización: crear apps y gestionar otras claves API. |
Puedes crear hasta 16 claves API de app por app y 16 claves API de organización por organización.
Clave API de app
Usa una Clave API de app para cualquier solicitud de la REST API limitada a una sola app: envío de mensajes; creación o actualización de usuarios; o lectura del historial de mensajes. El panel nunca muestra los valores de claves API existentes. La cadena en la columna Key ID es solo un identificador interno, no la clave. Para volver a tener un secreto funcional, sigue los pasos a continuación para crear una nueva clave API o rota una clave existente. La rotación genera un nuevo valor manteniendo el mismo Key ID, nombre y lista de permitidos de IP, y el valor antiguo deja de funcionar inmediatamente.
Ve a Settings > Keys & IDs de la app
En el panel de OneSignal, selecciona tu app y ve a Settings > Keys & IDs.
Haz clic en Add Key
Introduce un nombre descriptivo (por ejemplo,
Backend service). Opcionalmente, añade una lista de permitidos de IP para que la clave solo funcione desde servidores aprobados.
Clave API de organización
Usa una Clave API de organización para operaciones que abarcan todas las apps de tu organización. Endpoints comunes:- Gestión de apps: Crear una app, Ver apps
- Gestión de claves API: Crear clave API, Eliminar clave API, Rotar clave API
Ve a Keys & IDs de la organización
En el panel de OneSignal, ve a Organizations > Tu organización > Keys & IDs.
Haz clic en Add Key y dale un nombre
Introduce un nombre descriptivo (por ejemplo,
App provisioning). Opcionalmente, añade una lista de permitidos de IP.
Lista de permitidos de IP
La lista de permitidos de IP es opcional, pero muy recomendable. Restringe el uso de la clave API a direcciones IP específicas, de modo que una clave filtrada no pueda usarse desde otro lugar.- Introduce bloques CIDR separados por espacios (ejemplo:
192.0.2.0/24 192.0.2.123/32). - Las solicitudes desde IPs no permitidas se rechazan.
- Servicios backend con IPs estáticas.
- Entornos de producción de alta seguridad.
Gestionar claves API
Después de crear una clave, puedes editarla, rotarla o eliminarla desde la lista de claves en Settings > Keys & IDs. Las Claves API de app también admiten estas operaciones a través de la REST API. Las Claves API de organización solo se gestionan en el panel.Editar una clave
Actualiza el nombre o la lista de permitidos de IP sin cambiar el valor secreto. No se requieren cambios en la integración. Usa el panel, o la API de Update API key (solo Claves API de app).Rotar una clave
La rotación genera un nuevo secreto manteniendo el mismo Key ID, nombre y lista de permitidos de IP. El secreto antiguo deja de funcionar inmediatamente. Rota una clave cuando:- La clave se haya expuesto.
- Un miembro del equipo con acceso se vaya.
- Toque una rotación de seguridad de rutina.
- Hayas perdido el valor original de la clave y necesites un secreto funcional.
Eliminar una clave
La eliminación quita la clave permanentemente y bloquea de inmediato el acceso a la API que la utilizaba. Usa la eliminación cuando una clave ya no sea necesaria. Usa el panel, o la API de Delete API key (solo Claves API de app).Migrar desde claves API heredadas
OneSignal introdujo las Claves API de app y de organización (con nombres, rotación y lista de permitidos de IP) en noviembre de 2024. La clave User Auth heredada y la clave REST API original siguen siendo aceptadas, pero la interfaz de gestión para ellas se ha eliminado y no se pueden crear nuevas claves.Crea una nueva clave
Crea una nueva Clave API de app o Clave API de organización según la clave heredada que estés reemplazando.
Actualiza tu código
Reemplaza la clave heredada con el nuevo valor en cada servicio que se autentique contra OneSignal.
Actualiza la URL base de la API
Cambia la URL base de tu API de
https://onesignal.com/api/v1/ a https://api.onesignal.com.Verifica las solicitudes a la API en staging antes de desactivar tu clave heredada en producción.
Bloquear el acceso a la API
Para revocar una clave de inmediato, rótala o elimínala en Settings > Keys & IDs. Las solicitudes que usen el valor antiguo fallan de inmediato. Para detener el envío de mensajes o pausar una app por completo, consulta Apps y organizaciones deshabilitadas.Mejores prácticas de seguridad
- Almacena las claves API en un backend seguro (nunca del lado del cliente).
- Usa variables de entorno o un gestor de secretos.
- Habilita la lista de permitidos de IP cuando sea posible.
- Rota las claves periódicamente.
- Usa claves separadas para staging y producción.
Preguntas frecuentes
¿Cómo encuentro mi clave API?
Los valores de las claves API comienzan conos_v2_app_ y solo se muestran una vez, inmediatamente después de crear o rotar la clave. La columna Key ID del panel es un identificador interno, no la clave API, y devuelve 401 Unauthorized si se usa para autenticación. Si no guardaste el valor de tu clave, rota la clave para generar uno nuevo. Consulta Clave API de app o Clave API de organización para ver el flujo completo.
¿Puedo recuperar una Clave API de app heredada?
No. OneSignal ya no muestra las Claves API de app heredadas. Si no encuentras el valor en tu código, genera una nueva Clave API de app y actualiza tus integraciones.¿Cuál es la diferencia entre un App ID, una Clave API de app y una Clave API de organización?
- App ID: Un identificador público para tu app. Se usa en la configuración del SDK y en las solicitudes a la API para especificar la app.
- Clave API de app: Un secreto usado para enviar mensajes y gestionar usuarios de una app.
- Clave API de organización: Un secreto usado para gestionar apps y configuraciones a nivel de organización en toda tu cuenta.
¿Qué pasa si mi clave API se expone?
Rota la clave inmediatamente. La rotación invalida el valor antiguo y emite uno nuevo manteniendo el mismo Key ID, nombre y lista de permitidos de IP. Luego actualiza todos los servicios que usan la clave. Revisa tus registros de auditoría para detectar actividad inesperada en la API.Páginas relacionadas
Resumen de la REST API
Autentica solicitudes y comprende la REST API de OneSignal.
Límites de tasa
Límites de tasa por clave y buenas prácticas para integraciones de alto volumen.
Registros de auditoría
Revisa la actividad de la API y del panel por clave, usuario y tiempo.
Apps y organizaciones deshabilitadas
Pausa o cierra una app y comprende las implicaciones de facturación.