Autenticación de la API

Cómo funciona la autenticación

La API de Imara usa el flujo OAuth 2.0 Client Credentials. Este es el estándar para comunicaciones máquina a máquina (M2M) donde no hay un usuario humano interactuando en tiempo real.

El proceso es simple: usas tu Client ID y Client Secret para obtener un access token, y luego incluyes ese token en cada solicitud a la API.

Paso 1 — Obtener un Access Token

Envía una solicitud POST al endpoint de token:

POST https://auth.imara.com/oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=TU_CLIENT_ID
&client_secret=TU_CLIENT_SECRET
&resource=https://api.imara.com

Respuesta exitosa:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

El token expira en 1 hora (3600 segundos). Deberás solicitar uno nuevo cuando expire.

Paso 2 — Usar el token en tus solicitudes

Incluye el token en el header Authorization de cada solicitud:

GET https://api.imara.com/v1/controls
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Manejo de tokens expirados

Cuando un token expire, recibirás una respuesta 401 Unauthorized. Simplemente solicita un nuevo token usando el mismo proceso y reanuda tus solicitudes.

Te recomendamos implementar lógica de renovación automática en tu aplicación — guarda la hora de expiración y renueva el token antes de que expire, en lugar de esperar a recibir el error.

Ejemplo completo (cURL)

# 1. Obtener token
TOKEN=$(curl -s -X POST https://auth.imara.com/oidc/token \
  -d "grant_type=client_credentials" \
  -d "client_id=TU_CLIENT_ID" \
  -d "client_secret=TU_CLIENT_SECRET" \
  -d "resource=https://api.imara.com" \
  | jq -r '.access_token')

# 2. Usar el token
curl https://api.imara.com/v1/controls \
  -H "Authorization: Bearer $TOKEN"

Seguridad

• Nunca expongas tu Client Secret en código cliente o repositorios públicos
• Usa variables de entorno o sistemas de gestión de secretos (AWS Secrets Manager, HashiCorp Vault, etc.)
• Rota tus claves periódicamente como medida de seguridad preventiva
• Usa una clave diferente por entorno (producción vs. staging)