Autenticacion — API de Nomyt

La API de Nomyt utiliza autenticacion basada en tokens Bearer (OAuth 2.0) para proteger el acceso a los recursos de vacantes, candidatos y entrevistas.

Obtener un token de acceso

Paso 1: Crear una aplicacion API

1. Ve a Ajustes > API > Aplicaciones.
2. Haz clic en + Nueva aplicacion.
3. Completa los datos:
   • Nombre de la aplicacion
   • URL de redireccion (para flujo OAuth)
   • Scopes requeridos
4. Guarda y copia tu client_id y client_secret.

Seguridad

El client_secret solo se muestra una vez al momento de crearlo. Guardalo en un lugar seguro. Si lo pierdes, deberas generar uno nuevo.

Paso 2: Solicitar un token

curl -X POST https://api.nomyt.co/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "tu_client_id",
    "client_secret": "tu_client_secret",
    "scope": "vacancies:read vacancies:write candidates:read"
  }'

Respuesta exitosa

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "vacancies:read vacancies:write candidates:read"
}

Paso 3: Usar el token

Incluye el token en el header Authorization de cada peticion:

curl -X GET https://api.nomyt.co/v1/vacancies \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Scopes disponibles

Scope	Descripcion	Permisos
vacancies:read	Lectura de vacantes	Consultar vacantes, estados, metricas y detalles de publicaciones.
vacancies:write	Gestion de vacantes	Crear, editar, publicar, pausar y cerrar vacantes.
candidates:read	Lectura de candidatos	Consultar perfiles de candidatos, aplicaciones y estados.
candidates:write	Gestion de candidatos	Actualizar etapas, agregar notas, importar candidatos.
interviews:manage	Gestion de entrevistas	Agendar, reagendar, cancelar entrevistas y registrar evaluaciones.

Principio de minimo privilegio

Si tu aplicacion solo necesita consultar vacantes publicadas, usa unicamente vacancies:read. No solicites scopes de escritura o gestion innecesariamente.

Combinaciones comunes de scopes

Caso de uso	Scopes recomendados
Portal de empleo externo	vacancies:read
Sistema de RH integrado	vacancies:read vacancies:write candidates:read candidates:write
Herramienta de agenda	interviews:manage candidates:read
Dashboard de analiticas	vacancies:read candidates:read
Integracion completa	vacancies:read vacancies:write candidates:read candidates:write interviews:manage

Renovacion de tokens

Los tokens tienen una vigencia de 1 hora (3600 segundos). Para renovar:

curl -X POST https://api.nomyt.co/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "tu_refresh_token",
    "client_id": "tu_client_id"
  }'

Respuesta de renovacion

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "nuevo_refresh_token",
  "scope": "vacancies:read vacancies:write candidates:read"
}

Consejo

Implementa la renovacion automatica de tokens en tu aplicacion. Solicita un nuevo token cuando falten menos de 5 minutos para que expire el actual, evitando interrupciones en el servicio.

Errores de autenticacion

Codigo HTTP	Error	Descripcion
401	unauthorized	Token ausente, expirado o invalido.
403	forbidden	El token no tiene los scopes necesarios para la operacion solicitada.
429	rate_limited	Se excedio el limite de peticiones por minuto.

Ejemplo de error

{
  "error": "forbidden",
  "message": "El scope 'vacancies:write' es requerido para crear vacantes.",
  "hint": "Solicita un nuevo token con el scope adecuado."
}

Manejo de errores

# Verificar si el token es valido
curl -X GET https://api.nomyt.co/v1/auth/verify \
  -H "Authorization: Bearer {token}"

Respuesta con token valido:

{
  "valid": true,
  "scopes": ["vacancies:read", "vacancies:write", "candidates:read"],
  "expires_at": "2026-03-11T11:00:00Z",
  "application": "Mi App de RH"
}

Respuesta con token expirado:

{
  "valid": false,
  "error": "token_expired",
  "expired_at": "2026-03-11T10:00:00Z",
  "hint": "Usa el refresh_token para obtener un nuevo access_token."
}

Limites de tasa (Rate Limiting)

Plan	Limite API	Limite de vacantes
Gratuito	60 peticiones/minuto	3 vacantes activas
Profesional	300 peticiones/minuto	25 vacantes activas
Empresarial	1,000 peticiones/minuto	Vacantes ilimitadas

Los headers de respuesta incluyen informacion sobre tu consumo:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 285
X-RateLimit-Reset: 1709145600

Limite excedido

Cuando excedes el limite de tasa, la API responde con codigo 429 e incluye el header Retry-After indicando cuantos segundos debes esperar antes de la siguiente peticion.

Seguridad recomendada

Buenas practicas

• Nunca expongas el client_secret en codigo del frontend o repositorios publicos.
• Usa HTTPS exclusivamente para todas las comunicaciones con la API.
• Rota los secretos periodicamente y revoca tokens que ya no se utilicen.
• Limita los scopes a los estrictamente necesarios para tu aplicacion.
• Almacena tokens de forma segura (variables de entorno, gestores de secretos).