Autenticación y API keys

Cada request a /v1 se autentica con una API key. Las keys están ligadas a tu cuenta y llevan tu plan, que determina tu cuota y qué datos puedes leer.

Obtener una key

Regístrate en noms.sh, verifica tu correo y luego genera una key desde tu panel: Panel → Keys de API → Crear key. La key en bruto se muestra una sola vez al crearla y nunca se almacena, así que cópiala en un lugar seguro. Si la pierdes, revócala desde la misma pantalla y genera una nueva.

Si una key podría haberse filtrado, rótala en el sitio: Panel → Keys de API → Rotar. La rotación genera un secreto nuevo para la misma key, conserva su etiqueta, plan e historial de uso, revela el nuevo secreto una sola vez e invalida el secreto anterior de inmediato. Actualiza tus integraciones con el nuevo valor; el anterior deja de funcionar en cuanto rotas.

Tu key lleva tu plan

Las cuentas nuevas empiezan en el plan Taster. Mejora tu plan en Panel → Facturación y cualquier key que generes hereda la cuota y el acceso a datos de tu plan actual. Consulta el consumo por key en Panel → Uso.

Una key se ve como noms_sk_live_.... Trátala como una contraseña: nunca la subas al repositorio, nunca la incluyas en código del lado del cliente y rótala si se filtra.

Enviar tu key

Envía tu key en el header X-API-Key en cada request:

curl https://api.noms.sh/v1/foods?q=oats \
  -H "X-API-Key: $NOMS_KEY"

Bearer también funciona

Para clientes que lo prefieran, Authorization: Bearer <clave> se acepta y se comporta de forma idéntica a X-API-Key. Los ejemplos interactivos del resto de esta guía usan la forma Bearer. Cualquiera de las dos está bien.

Cuando la autenticación falla

Una key ausente, malformada, revocada, expirada o desconocida devuelve un 401 deliberadamente opaco. Nunca revelamos por qué falló una key, para no filtrar una señal de sondeo de keys:

401 Unauthorized

{
  "type": "/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid authentication is required to access this resource.",
  "doc_url": "https://api.noms.sh/docs#tag/unauthorized"
}

Próximos pasos

Consultas y modelo de datos: las cuatro palancas para leer datos, y el envoltorio en que vuelven.
Límites y cuotas: qué permite cada plan y cómo leer tu situación.