OAuth 2.0

OAuth 2.0 es el estándar de autorización utilizado por las APIs del Grupo INS. Define cómo una aplicación puede obtener acceso controlado a recursos protegidos sin necesidad de compartir credenciales directamente. ¿Qué es un Grant? Un grant es el método mediante el cual una aplicación obtiene autorización para acceder a recursos. OAuth 2.0 define distintos grants según el escenario de uso. El Grupo INS utiliza client_credentials.

Machine-to-Machine

Diseñado para comunicación servidor a servidor. No requiere autenticación ni consentimiento de usuarios finales.

Client Credentials

La aplicación se autentica con su propio client_id y client_secret para obtener untoken de acceso. Estas credenciales las otorga el Grupo INS.

Sin exposición de credenciales

Las credenciales nunca se comparten. Solo se intercambia un token temporal con expiración definida.

¿Por qué Client Credentials? Este flujo es ideal para integraciones entre sistemas. La aplicación cliente actúa en nombre propio, no en nombre de un usuario, lo que elimina la necesidad de formularios de login o pantallas de consentimiento.

Flujo de autenticación

Proceso completo desde la obtención de credenciales hasta el consumo de APIs protegidas, incluyendo la renovación del token al expirar.

1

Solicitud de token al endpoint OAuth

Dispone de client_id y client_secret asignados por el Grupo INS.

POST /connect/v1/token — grant_type=client_credentials.

2

Generación del token de acceso

Se devuelve un JWT firmado con expires_in y scope.

3

Consumo de API protegida

Authorization: Bearer {token} + subscription-key en cada request.

4

Respuesta del API

Estructura JSON

Solucitud de token

Para obtener un token de acceso envía una solicitud POST con las credenciales en el cuerpo de la petición.

POST /connect/v1/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Endpoints y ambientes

El Grupo INS dispone de dos ambientes: Integración para el desarrollo y validación de las implementaciones, y Producción para la operación del servicio en un entorno productivo.

Ejemplo cURL

Ejemplo completo para solicitar un token de acceso desde línea de comandos. Reemplaza your_client_id y your_client_secret con las credenciales asignadas por el Grupo INS.

curl --request POST \
  --url 'https://apiintegracion.grupoins.com/connect/v1/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id=your_client_id' \
  --data 'client_secret=your_client_secret'

Ejemplo POSTMAN

También puede configurar la herramienta Postman para obtener tokens de acceso, siguiendo los siguientes pasos:

1. Seleccionar la pestaña "Authorization".
2. En la lista desplegable "Auth Type", seleccionar "OAuth 2.0".
3. En el campo "Token Name" ingresar un nombre para identificar el token.
4. En la lista desplegable "Grant type" seleccionar "Client Credentials".
5. En el campo "Access Token URL" ingresar el URL para la obtención de tokens. Este varía según el ambiente.
6. En el campo "Client ID" ingresar su client_id.
7. En el campo "Client Secret" ingresar su client_secret.
8. En la lista "Client Authentication" seleccionar "Send as Basic Auth header".
9. Mediante el botón "Get New Access Token" se solicita el token de acceso. Esto despliega el siguiente diálogo.
10. Utilizar el botón "Use token" para cargar el token obtenido en la solicitud actual.

Si requiere conocer como obtener un token de acceso desde el código fuente, en este enlace encontrará ejemplos en los lenguajes de programación más comunes.

Respuesta del servidor OAuth

Al completar correctamente la solicitud el servidor responde con un objeto JSON que contiene el token de acceso y metadatos de sesión.

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

Uso del token de acceso

El token de acceso retornado por el servidor de autorización, debe enviarse en un encabezado HTTP para todos los llamados que se realicen a los APIs del Grupo INS. Este encabezado se denomina Authorization y tiene el siguiente formato:

Authorization: Bearer {token de acceso}

Donde {token de acceso} corresponde al valor del atributo access_token, retornado por el servidor de autorización. Ejemplo:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRt...

Clave de suscripción

Además del token de acceso, cada solicitud a las APIs del Grupo INS requiere un header adicional con la clave de suscripción. Ambos son obligatorios y deben enviarse simultáneamente. La clave de suscripción es entregada por el Grupo INS junto con el client_id y client_secret.

Token de acceso

Authorization: Bearer

Token JWT temporal generado mediante el flujo Client Credentials. Tiene expiración (expires_in) y debe renovarse periódicamente.

Propósito: autenticación de la aplicación

Requerido

Clave de suscripción

subscription-key

Clave estática asignada por el Grupo INS que identifica la suscripción a las APIs. No expira de forma automática.

Propósito: control de acceso y throttling

Requerido

Ejemplo de llamada a una API protegida:

HTTP Copiar

GET https://apiintegracion.grupoins.com/polizas/v1/recibos/consulta?numeroPoliza=ABCXYZ
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
subscription-key: f4027603-e270-4a2b-b633-5a6a1dad7785

Si falta cualquiera de los dos headers la API retornará un error de autenticación.

Protección de credenciales

Recomendaciones oficiales para proteger las credenciales y tokens de tu integración.

Conceptos clave

Glosario de términos utilizados en la autenticación y autorización de las APIs del Grupo INS.

Buenas prácticas para desarrolladores

Recomendaciones para una integración eficiente, robusta y segura con las APIs del Grupo INS.