En Supabase, las API Keys son credenciales que permiten que aplicaciones, servidores y servicios se autentiquen y accedan a los recursos de tu proyecto (base de datos, autenticación, almacenamiento, funciones Edge, etc.).
Cuando creas un proyecto, Supabase genera automáticamente varias claves. Cada una tiene un propósito específico y diferentes niveles de privilegios.
Arquitectura de autenticación en Supabase
Cuando una aplicación se conecta a Supabase, normalmente envía una API Key en los encabezados HTTP:
apikey: TU_API_KEY
Authorization: Bearer TU_API_KEY
Supabase utiliza estas claves junto con PostgreSQL Roles y las políticas RLS (Row Level Security) para determinar qué operaciones están permitidas.
Tipos de API Keys
Actualmente Supabase maneja principalmente:
- Publishable Key (Anónima)
- Secret Key
- JWT Secret (Interna)
- Service Role Key (Legado, pero todavía disponible)
Conexión directa PostgresQL
En la pantalla pricipal, buscamso el boton verde que dice connect.
Donde mostrará la siguiente pantalla de para conectar su proyecto.
Seleccionamos conexión directa y luego transacción pooler
Luego nos mostrará los datos de conexión que usaremos para PostgesQL
Publishable Key (anon)
Ingresamos a un Organización, luego a un proyecto.
Luego en el menú lateral derecho ingresamos a project settings donde buscamos API Keys, aparecerá la siguiente pantalla.
Esta es la clave que normalmente se utiliza desde:
- Frontend React
- Next.js
- Angular
- Vue
- Svelte
- Aplicaciones móviles
Ejemplo:
const supabase = createClient(
'https://xxxx.supabase.co',
'sb_publishable_xxxxxxxxx'
)
Características
- ✅ Puede exponerse públicamente.
- ✅ Se usa en navegadores.
- ✅ Respeta las políticas RLS.
- ✅ No tiene privilegios administrativos.
- ❌ No puede saltarse las restricciones de seguridad.
Caso práctico
Supongamos que tienes una tabla: post
Y una política:
CREATE POLICY "leer posts"
ON posts
FOR SELECT
USING (published = true);
Si un usuario utiliza la Publishable Key:
const { data } = await supabase
.from('posts')
.select('*');
Sólo verá los registros permitidos por la política.
Secret Key
Es una clave de alto privilegio diseñada para:
- Backends
- APIs privadas
- Microservicios
- Funciones del servidor
Ejemplo:
const supabase = createClient(
process.env.SUPABASE_URL,
process.env.SUPABASE_SECRET_KEY
)
Características
- ✅ Acceso privilegiado.
- ✅ Sólo debe existir en el servidor.
- ✅ Nunca debe enviarse al navegador.
- ❌ Si se filtra, alguien podría comprometer el proyecto.
Casos de uso
API Backend
Cliente
v
Backend Node.js
v
Supabase
Procesamiento interno
- Facturación
- Reportes
- Integraciones externas
- ETL
- Cron Jobs
Service Role Key
Durante mucho tiempo fue la clave administrativa principal.
Ejemplo: service_role
Esta clave utiliza el rol PostgreSQL: service_role
Características
- ✅ Omite las políticas RLS.
- ✅ Puede leer y escribir cualquier dato.
- ✅ Acceso total a la base de datos mediante la API.
- ❌ Nunca debe estar en el frontend.
Ejemplo
Tabla:
usuarios
Política:
Solo puede ver sus propios datos
Con la clave anónima:
select *
from usuarios
Sólo devuelve los registros permitidos.
Con la Service Role:
select *
from usuarios
Obtiene todos los registros.
JWT Secret
Esta no suele utilizarse directamente en aplicaciones.
Supabase la usa internamente para:
- Firmar JWT
- Validar sesiones
- Generar tokens de acceso
Ejemplo conceptual: eyJhbGciOiJIUzI1NiIs...
Firmado usando: JWT_SECRET
¿Cuándo se usa?
Principalmente:
- Integraciones avanzadas
- Sistemas SSO
- Proveedores de autenticación personalizados
- Generación manual de JWT
La mayoría de los desarrolladores nunca necesitan usarla.
Preguntas frecuentes
¿Dónde ver las API Keys?
En el Dashboard:
Proyecto
└── Settings
└── API
Allí encontrarás:
- Project URL
- Publishable Key
- Secret Key
- JWT Secret
¿Cómo se generan?
Cuando creas un proyecto: Create New Project
Supabase genera automáticamente:
- URL del proyecto
- Publishable Key
- Secret Key
- JWT Secret
No necesitas crearlas manualmente.
¿Cómo rotar (regenerar) una API Key?
En:
Settings
└── API
Puedes regenerar determinadas claves.
La rotación es recomendable cuando:
- Una clave se filtró.
- Un desarrollador abandonó el equipo.
- Existe sospecha de acceso no autorizado.
Después de regenerarla:
Clave antigua -> inválida
Clave nueva -> válida
Debes actualizar:
- Variables de entorno
- Docker
- Kubernetes Secrets
- GitHub Actions
- Servidores
Resumen
| Clave | Frontend | Backend | Respeta RLS | Nivel de acceso |
|---|---|---|---|---|
| Publishable (anon) | Sí | Sí | Sí | Bajo |
| Secret Key | No | Sí | Puede realizar operaciones privilegiadas | Alto |
| Service Role | No | Sí | No | Total |
| JWT Secret | No | Interno | N/A | Interno |
La regla más importante en Supabase es: la Publishable Key puede vivir en el navegador; la Secret Key y la Service Role nunca deben exponerse fuera del servidor. De lo contrario, cualquier persona podría obtener acceso privilegiado a tu proyecto.