Cómo crear y gestionar claves de API en Simbase

Una clave de API autentica tus solicitudes a la API de Simbase. Cada clave recibe al crearla un conjunto de permisos que ya no cambian. Una clave puede servir a varias integraciones, pero es más seguro usar una clave por integración. Las claves se crean y gestionan en el panel, en Integrations → API.

Crear una clave de API

Inicia sesión en dashboard.simbase.com.
Ve a Integrations → API.
Haz clic en Create New API Key.
Ponle a la clave un nombre que indique para qué sirve, por ejemplo Usage Guard Toolkit. El nombre es solo una etiqueta. Aparece en tu lista de claves y en ningún otro sitio.
En Resources, define los permisos que necesita la clave. Consulta Permisos más abajo.
Haz clic en Create API Key y copia la clave.

Copia la clave ahoraSimbase muestra la clave una sola vez, en el diálogo "Keep your key safe". Haz clic en la clave para copiarla y guárdala en un gestor de contraseñas o en el almacén de secretos de tu plataforma. Si la pierdes, no hay forma de volver a verla. Elimina la clave y crea una nueva.

Mira la demo de abajo para ver los pasos uno a uno:

Permisos

Los permisos se definen por recurso, en uno de tres niveles. None significa que la clave no tiene acceso a ese recurso. Es el valor por defecto en cada fila. Read consulta datos sin cambiar nada. Write crea, modifica y elimina. Al elegir Write también se selecciona Read en la misma fila, porque todo lo que escribe tiene que leer primero.

No todos los recursos ofrecen los tres niveles. Account y Usage son de solo lectura, así que muestran None y Read. SIM card state, Reset, Registration y Auto-disable son acciones, no datos, así que muestran None y Write.

El árbol de recursos

Recurso	Niveles	Incluye
All resources	None, Read, Write	Todas las filas de abajo a la vez
Account	None, Read	Los datos de tu cuenta: organización, usuarios y roles, saldo
Usage	None, Read	Registros de uso: historial de datos, SMS y sesiones
SIM cards	None, Read, Write	Todo el grupo SIM cards de abajo
– SIM card details	None, Read, Write	El registro de la SIM: etiqueta, Tags, plan de cobertura, IP pública, límites de uso y bloqueo de IMEI
– SIM card state	None, Write	Activar y desactivar SIM
– Reset	None, Write	Reiniciar la conexión: termina la sesión de datos actual para que pueda abrirse una nueva
– SMS	None, Read, Write	Leer el historial de mensajes y enviar mensajes
– Registration	None, Write	Registrar nuevas SIM en la cuenta
– Auto-disable	None, Write	Fijar y borrar la fecha de Auto-disable
Utilities	None, Read	Todo el grupo Utilities de abajo
– Geo	None, Read	Consultas de Cell ID: la antena a la que está conectada una SIM
Integrations	None, Read, Write	Todo el grupo Integrations de abajo
– Webhooks	None, Read, Write	Listar, crear y eliminar endpoints de webhook

Recurso

All resources
Account
Usage
SIM cards
– SIM card details
– SIM card state
– Reset
– SMS
– Registration
– Auto-disable
Utilities
– Geo
Integrations
– Webhooks

Filas principales y secundarias

SIM cards, Utilities e Integrations tienen una flecha junto al nombre. Haz clic en ella para desplegar los permisos individuales.

Al fijar un nivel en una fila principal, cada fila secundaria recibe ese nivel, o el más alto que ofrezca. Si pones All resources en Write, Account y Usage reciben Read, porque es lo máximo que admiten.
Si fijas solo una fila secundaria, la fila principal no muestra ninguna selección. Es lo esperado. Una fila principal solo muestra un nivel cuando todas sus filas secundarias coinciden.

Elegir un nivel

Da solo lo que la integración necesita. Una clave que solo puede leer el uso no puede desactivar una SIM si se filtra.

La integración…	Asignar
Informa sobre el consumo de datos	Usage: Read y SIM card details: Read
Desactiva SIM al final de un bono de datos	SIM card state: Write
Activa la protección antirrobo o la desactiva	SIM card details: Write
Reenvía o envía SMS	SMS: Write
Registra nuevas SIM	Registration: Write
Ejecuta el Usage Guard Toolkit	All resources: Write

La integración…

Informa sobre el consumo de datos
Desactiva SIM al final de un bono de datos
Activa la protección antirrobo o la desactiva
Reenvía o envía SMS
Registra nuevas SIM
Ejecuta el Usage Guard Toolkit

En la referencia de la API aparecen como nombres de scope construidos con el mismo árbol. SIM card details corresponde a simcards.details:read y simcards.details:write.

Configuración avanzada

Activa Show advanced settings para ver dos campos opcionales. Puedes dejar ambos en blanco.

IP restrictions

Limita la clave a una sola dirección IP de confianza o a un rango en notación CIDR. Las solicitudes desde cualquier otra dirección se rechazan. Deja el campo vacío para no aplicar ninguna restricción. La lista de claves mostrará entonces 0.0.0.0/0 en Allowed IPs, es decir, cualquier dirección.

Solo direcciones fijasUsa una restricción de IP cuando la integración funcione desde una dirección fija, como tu propio servidor o una pasarela NAT. Las plataformas de automatización alojadas como Make.com y Zapier llaman desde un grupo de direcciones que va rotando, así que restringir la clave por IP hará que dejen de funcionar.

Expires in (number of days)

Los días desde la creación hasta que la clave deja de funcionar. Escribe 31 y la clave caduca dentro de 31 días. Si dejas el campo vacío, la clave no caduca nunca.

Las claves de corta duración son útiles para migraciones puntuales, acceso de contratistas y cualquier cosa que, si no, tendrías que acordarte de revocar.

Gestionar tus claves

La lista de API muestra todas las claves de la cuenta: su nombre, un Key ID truncado, el nivel de permisos con que se creó, cuándo se usó por última vez y su restricción de IP. Last API call se muestra en la zona horaria de tu cuenta, y Allowed IPs muestra 0.0.0.0/0 cuando no hay restricción.

El Key ID solo sirve para distinguir unas claves de otras. Está truncado y no sirve para autenticarse.

Los permisos se fijan al crear la clave y no se pueden editar después. Para cambiar lo que puede hacer una clave, crea una nueva con los permisos que quieras, cambia tu integración a ella y elimina la antigua.

El menú de tres puntos al final de cada fila tiene una sola opción: Delete. Una clave eliminada deja de funcionar al instante y las solicitudes que la usan fallan en la autenticación.

Usar la clave

Envía la clave como bearer token en cada solicitud:

Solicitud

GET /v2/simcards HTTP/1.1
Host: api.simbase.com
Authorization: Bearer YOUR_API_KEY

La documentación completa de los endpoints está en developer.simbase.com.

Preguntas frecuentes

No. Los permisos se fijan al crearla y ya no cambian. Crea una clave de reemplazo con los permisos que necesitas, pasa tu integración a ella y elimina la clave antigua.

No. La clave completa se muestra una sola vez, al crearla. La lista solo muestra un Key ID truncado, que no sirve para autenticarse. Elimina la clave y crea una nueva.

Que la clave no tiene restricción de IP y acepta solicitudes desde cualquier dirección. Es lo que obtienes si dejas vacío el campo IP restrictions.

Nada te impide usar una misma clave en varias integraciones, pero una clave por integración merece ese minuto extra. Puedes limitar cada una a lo que necesita, ver en la columna Last API call cuál sigue en uso, y eliminar o renovar una sin romper las demás. Una clave compartida tiene que llevar los permisos de todas juntas, y revocarla lo tumba todo a la vez.