Saltar al contenido principal

Autenticación

Autenticación

La autenticación es la capa que permite identificar de forma segura a la integración que llama a la API.

En Soyio, esto se resuelve con API keys. Cada API key representa a un servicio y entrega un secret JWT para autenticar requests.

Una vez autenticada la key, la autorización define qué operaciones puede ejecutar. Si quieres entender esa segunda capa, revisa la guía de autorización.

Usa HTTPS para todos los requests. Requests por HTTP retornan 403.

Guarda secret y refresh_token en un secret manager. Ambos son sensibles.

API keys​

Las API keys sirven para autenticar integraciones server-to-server con Soyio.

Cada API key:

  • pertenece a un entorno (sandbox o production)
  • autentica requests usando Authorization: Bearer <secret_jwt>
  • puede tener expiración
  • puede incluir un refresh_token para renovación
  • define su acceso a la API a traves de permisos

Puedes revisar y gestionar tus API keys en el dashboard de Soyio. La API también permite crear, actualizar, renovar y revocar keys cuando necesitas automatizar ese ciclo de vida.

Autenticación responde la pregunta "quién está llamando".

Autorización responde la pregunta "qué puede hacer".

Entornos​

Hoy existen dos tipos de API key:

  • Sandbox: prefijo ak_sandbox_
  • Production: prefijo ak_live_

Por defecto:

  • Las keys de production expiran en 90 dias
  • Las keys de sandbox no expiran

El header Authorization debe usar el secret JWT, no el identificador ak_sandbox_... o ak_live_....

Si estás probando una integración nueva, revisa también la guía de modo sandbox.

Cómo enviar el header de autenticación​

Usa este formato:

Authorization: Bearer <secret_jwt>

<secret_jwt> corresponde al campo secret que recibes al crear o renovar una API key.

Cómo gestionar API keys​

La forma más simple de administrarlas es desde el dashboard de Soyio. Si tu integración necesita automatizar este flujo, usa la referencia de API:

Crear una API key​

Al crear una API key recibes, según el caso:

  • secret para autenticar requests
  • refresh_token cuando la key tiene expiracion

Ejemplo mínimo:

{
  "api_key": {
    "label": "Integration Worker",
    "expires_in_days": 30,
    "permissions": [
      "consent_actions.api.read",
      "api_keys.api.manage"
    ]
  }
}

Para detalles de permisos, usa la guía de autorización.

Los nombres de permisos siguen los recursos de la API Reference, por ejemplo branches.api.write, products.api.manage o data_subject_requests.api.config.

secret y refresh_token se muestran solo en creación y renovación.

Renovar una API key​

Cuando una API key tiene expiración, puedes renovarla con su refresh_token. La renovación devuelve un nuevo secret y un nuevo refresh_token.

Ejemplo mínimo de payload:

{
  "api_key": {
    "refresh_token": "akrt_abc123xyz"
  }
}

Si quieres extender la expiración al renovar, puedes enviar también expires_in_days.

Cuándo renovar​

  • antes de que expire la key, para evitar interrupciones
  • inmediatamente si rotas secretos por seguridad
  • después de expirar, mientras el refresh_token siga vigente
Periodo de gracia del refresh token

Después de que expira una API key, su refresh_token sigue vigente por 60 días.

Si no renuevas dentro de ese periodo, debes crear una API key nueva.

Revocar una API key​

Revoca una API key cuando:

  • una integracion ya no se usa
  • sospechas exposicion del secret
  • estas reemplazando una key por otra

Una key revocada deja de autenticar requests.

Buenas prácticas​

  • usa una API key por servicio o integracion
  • asigna solo los permisos minimos necesarios
  • separa keys de sandbox y production
  • rota y revoca keys como parte de tu operacion normal
  • guarda secret y refresh_token en un secret manager

Siguiente paso​

Ahora revisa la guía de autorización para entender cómo se evalúa el acceso endpoint por endpoint.